Generated from `@cosmoops/connect-sdk/mcp`'s TypeScript source and its own doc comments - see [Reference](/docs/reference) for the other entry points. Regenerated on every deploy; don't hand-edit.

## Interfaces

### Interface: ConnectMcpSignatureVerdict [#interface-connectmcpsignatureverdict]

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| `valid` | `boolean` | - |
| `version` | `"v1"` \| `"v2"` \| `null` | Which scheme verified. `null` when nothing did. |
| `nonce` | `string` \| `null` | The signed nonce - present only for a verified `v2`, since `v1` does not sign it and an unsigned value is worth nothing as a replay key. |
| `timestamp` | `number` \| `null` | The signed timestamp, when the request verified. |

***

### Interface: McpSignaturePayloadV2Input [#interface-mcpsignaturepayloadv2input]

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| `timestamp` | `number` | The header's `t`, unix seconds. |
| `nonce` | `string` | The header's `n`, 32 lowercase hex characters. |
| `method` | `string` | - |
| `url` | `string` \| `URL` | The request URL as your server received it; only `pathname + search` is signed. |
| `authorization` | `string` \| `null` \| `undefined` | The raw `Authorization` header value (e.g. `"Bearer …"`), or null when absent. |
| `rawBody` | `string` | - |

***

### Interface: McpToolDescriptor [#interface-mcptooldescriptor]

One entry of an MCP `tools/list` response.

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| `name` | `string` | - |
| `title` | `string` | - |
| `description` | `string` | - |
| `inputSchema` | `Record`\<`string`, `unknown`\> | - |
| `annotations` | \{ `readOnlyHint`: `boolean`; `destructiveHint`: `boolean`; `idempotentHint`: `boolean`; \} | - |
| `annotations.readOnlyHint` | `boolean` | - |
| `annotations.destructiveHint` | `boolean` | - |
| `annotations.idempotentHint` | `boolean` | - |
| `_meta?` | [`McpToolMeta`](#interface-mcptoolmeta) | See `mcpToolMeta`. Absent unless something is declared. |

***

### Interface: McpToolMeta [#interface-mcptoolmeta]

The `_meta` Connect reads from a tool definition.

#### Indexable

```ts
[key: string]: unknown
```

#### Properties

| Property | Type |
| ------ | ------ |
| `cosmoops.com/foundational?` | `boolean` |

***

### Interface: StoreDataPort [#interface-storedataport]

The subset of `ConnectClient["data"]` a toolset uses.

Structural rather than the concrete class so this module pulls in neither the
transport nor the key-holding client, and so a test can pass a recording
double without a network seam of its own.

#### Methods

##### get()

```ts
get(input: {
  workspaceId?: string;
  collection: string;
  id: string;
  asUser?: string;
}): Promise<StoreDocument>;
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | \{ `workspaceId?`: `string`; `collection`: `string`; `id`: `string`; `asUser?`: `string`; \} |
| `input.workspaceId?` | `string` |
| `input.collection` | `string` |
| `input.id` | `string` |
| `input.asUser?` | `string` |

###### Returns

`Promise`\<[`StoreDocument`](/docs/reference/core#interface-storedocument)\>

***

##### query()

```ts
query(input: {
  workspaceId?: string;
  collection: string;
  filters?: StoreQueryFilter[];
  orderBy?: StoreOrderBy;
  limit?: number;
  cursor?: string | null;
  asUser?: string;
}): Promise<{
  items: StoreDocument[];
  nextCursor: string | null;
}>;
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | \{ `workspaceId?`: `string`; `collection`: `string`; `filters?`: [`StoreQueryFilter`](/docs/reference/core#interface-storequeryfilter)[]; `orderBy?`: [`StoreOrderBy`](/docs/reference/core#interface-storeorderby); `limit?`: `number`; `cursor?`: `string` \| `null`; `asUser?`: `string`; \} |
| `input.workspaceId?` | `string` |
| `input.collection` | `string` |
| `input.filters?` | [`StoreQueryFilter`](/docs/reference/core#interface-storequeryfilter)[] |
| `input.orderBy?` | [`StoreOrderBy`](/docs/reference/core#interface-storeorderby) |
| `input.limit?` | `number` |
| `input.cursor?` | `string` \| `null` |
| `input.asUser?` | `string` |

###### Returns

`Promise`\<\{
  `items`: [`StoreDocument`](/docs/reference/core#interface-storedocument)[];
  `nextCursor`: `string` \| `null`;
\}\>

***

##### aggregate()

```ts
aggregate(input: {
  workspaceId?: string;
  collection: string;
  aggregations: StoreAggregation[];
  filters?: StoreQueryFilter[];
  asUser?: string;
}): Promise<{
  values: Record<string, number | null>;
}>;
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | \{ `workspaceId?`: `string`; `collection`: `string`; `aggregations`: [`StoreAggregation`](/docs/reference/core#interface-storeaggregation)[]; `filters?`: [`StoreQueryFilter`](/docs/reference/core#interface-storequeryfilter)[]; `asUser?`: `string`; \} |
| `input.workspaceId?` | `string` |
| `input.collection` | `string` |
| `input.aggregations` | [`StoreAggregation`](/docs/reference/core#interface-storeaggregation)[] |
| `input.filters?` | [`StoreQueryFilter`](/docs/reference/core#interface-storequeryfilter)[] |
| `input.asUser?` | `string` |

###### Returns

`Promise`\<\{
  `values`: `Record`\<`string`, `number` \| `null`\>;
\}\>

***

##### create()

```ts
create(input: {
  workspaceId?: string;
  collection: string;
  data: Record<string, unknown>;
  id?: string;
  asUser?: string;
}): Promise<StoreDocument>;
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | \{ `workspaceId?`: `string`; `collection`: `string`; `data`: `Record`\<`string`, `unknown`\>; `id?`: `string`; `asUser?`: `string`; \} |
| `input.workspaceId?` | `string` |
| `input.collection` | `string` |
| `input.data` | `Record`\<`string`, `unknown`\> |
| `input.id?` | `string` |
| `input.asUser?` | `string` |

###### Returns

`Promise`\<[`StoreDocument`](/docs/reference/core#interface-storedocument)\>

***

##### update()

```ts
update(input: {
  workspaceId?: string;
  collection: string;
  id: string;
  data: Record<string, unknown>;
  asUser?: string;
}): Promise<StoreDocument>;
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | \{ `workspaceId?`: `string`; `collection`: `string`; `id`: `string`; `data`: `Record`\<`string`, `unknown`\>; `asUser?`: `string`; \} |
| `input.workspaceId?` | `string` |
| `input.collection` | `string` |
| `input.id` | `string` |
| `input.data` | `Record`\<`string`, `unknown`\> |
| `input.asUser?` | `string` |

###### Returns

`Promise`\<[`StoreDocument`](/docs/reference/core#interface-storedocument)\>

***

##### delete()

```ts
delete(input: {
  workspaceId?: string;
  collection: string;
  id: string;
  asUser?: string;
}): Promise<void>;
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | \{ `workspaceId?`: `string`; `collection`: `string`; `id`: `string`; `asUser?`: `string`; \} |
| `input.workspaceId?` | `string` |
| `input.collection` | `string` |
| `input.id` | `string` |
| `input.asUser?` | `string` |

###### Returns

`Promise`\<`void`\>

***

### Interface: StoreTool [#interface-storetool]

One derived tool: the wire definition, and the call behind it.

Shaped so `listTools`/`callTool` can be answered without this module knowing
what transport is in front of it - see the note on `createStoreToolset`.

#### Properties

| Property | Type |
| ------ | ------ |
| `name` | `string` |
| `title` | `string` |
| `description` | `string` |
| `inputSchema` | [`JsonSchema`](#type-alias-jsonschema) |
| `annotations` | \{ `readOnlyHint`: `boolean`; `destructiveHint`: `boolean`; `idempotentHint`: `boolean`; \} |
| `annotations.readOnlyHint` | `boolean` |
| `annotations.destructiveHint` | `boolean` |
| `annotations.idempotentHint` | `boolean` |

#### Methods

##### execute()

```ts
execute(args: Record<string, unknown>): Promise<unknown>;
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `args` | `Record`\<`string`, `unknown`\> |

###### Returns

`Promise`\<`unknown`\>

***

### Interface: StoreToolset [#interface-storetoolset]

#### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| `tools` | `readonly` | readonly [`StoreTool`](#interface-storetool)[] | The derived tools, if you would rather register them yourself. |

#### Methods

##### listTools()

```ts
listTools(): {
  tools: McpToolDescriptor[];
};
```

###### Returns

```ts
{
  tools: McpToolDescriptor[];
}
```

###### tools

```ts
tools: McpToolDescriptor[];
```

***

##### callTool()

```ts
callTool(name: string, args: Record<string, unknown>): Promise<McpToolResult>;
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
| `args` | `Record`\<`string`, `unknown`\> |

###### Returns

`Promise`\<[`McpToolResult`](#type-alias-mcptoolresult)\>

***

### Interface: StoreToolsetOptions [#interface-storetoolsetoptions]

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| `collections` | readonly [`StoreCollectionDeclaration`](/docs/reference/core#interface-storecollectiondeclaration)[] | The application's own declaration - the same array seeded to `Application.storeSchema`. |
| `data` | [`StoreDataPort`](#interface-storedataport) | - |
| `asUser` | `string` \| (() => `string` \| `Promise`\<`string`\>) | The end user's Connect session token. Every call is made on their behalf. A function is resolved per call, for a toolset outliving one session. |
| `workspaceId?` | `string` | Omit for an application-scoped collection; required for a workspace-scoped one. |
| `writes?` | [`StoreToolWrites`](#type-alias-storetoolwrites) | - |
| `prefix?` | `string` | Prepended to every tool name, for a server mounting more than one source. |
| `include?` | readonly `string`[] | Collections to derive from. Defaults to every declared `data` collection. |
| `foundational?` | readonly `string`[] | Tool names (as listed, prefix included) to declare foundational - offered by Connect's workspace assistant on every turn, whatever the question. Connect honours at most four per application; pick the entry points (search, summary) the other tools take ids from. See `MCP_FOUNDATIONAL_META_KEY`. |
## Type Aliases

### Type Alias: JsonSchema [#type-alias-jsonschema]

```ts
type JsonSchema = Record<string, unknown>;
```

A JSON Schema object, as the MCP `tools/list` response carries it.

***

### Type Alias: McpToolResult [#type-alias-mcptoolresult]

```ts
type McpToolResult = {
  content: {
     type: "text";
     text: string;
  }[];
  isError?: boolean;
};
```

An MCP `tools/call` result.

A **type alias rather than an interface**, and that is load-bearing rather
than a style choice. The MCP SDK types a request handler's return as a union
whose members carry an index signature (`[x: string]: unknown`); an interface
is not assignable to such a type, while a type alias is - TypeScript grants
the implicit index signature only to the latter. Declared as an interface,
the four-line wiring in this file's own example does not compile, and the
caller is pushed into a cast at exactly the boundary where a cast hides
shape errors.

#### Properties

##### content

```ts
content: {
  type: "text";
  text: string;
}[];
```

###### type

```ts
type: "text";
```

###### text

```ts
text: string;
```

***

##### isError?

```ts
optional isError?: boolean;
```

***

### Type Alias: StoreToolWrites [#type-alias-storetoolwrites]

```ts
type StoreToolWrites = "none" | "create" | "all";
```

How much of the write surface to derive.

Defaults to `"none"`. A toolset is usually handed to a model driving somebody
else's conversation, and the blast radius of a derived `delete` on every
collection is not something to acquire by default - opting in is one word,
and discovering it by accident is not recoverable.

***

### Type Alias: VerifyConnectMcpSignatureInput [#type-alias-verifyconnectmcpsignatureinput]

```ts
type VerifyConnectMcpSignatureInput = {
  header: string | null | undefined;
  rawBody: string;
  method: string;
  url: string | URL;
  authorization: string | null | undefined;
  toleranceSeconds?: number;
  requireV2?: boolean;
  now?: Date;
} & 
  | {
  signingKey: string;
  apiKey?: never;
}
  | {
  apiKey: string;
  signingKey?: never;
};
```

#### Type Declaration

##### header

```ts
header: string | null | undefined;
```

The `Connect-Signature` header, or null when absent.

##### rawBody

```ts
rawBody: string;
```

The **raw** body - verify before parsing, never re-serialise. `""` for a GET.

##### method

```ts
method: string;
```

##### url

```ts
url: string | URL;
```

`request.url`, exactly as your server received it.

##### authorization

```ts
authorization: string | null | undefined;
```

The raw `Authorization` header value, or null when absent.

##### toleranceSeconds?

```ts
optional toleranceSeconds?: number;
```

Default 300. A timestamp this far from `now`, either way, fails.

##### requireV2?

```ts
optional requireV2?: boolean;
```

Refuse a header that verifies only as `v1`.

##### now?

```ts
optional now?: Date;
```
## Variables

### Variable: MCP\_FOUNDATIONAL\_META\_KEY [#variable-mcp_foundational_meta_key]

```ts
const MCP_FOUNDATIONAL_META_KEY: "cosmoops.com/foundational" = "cosmoops.com/foundational";
```

The `_meta` key that marks a tool **foundational**: Connect's workspace
assistant offers it on every turn, before ranking the rest of a workspace's
application tools against the question.

Connect keeps only this key of a tool's `_meta`, honours it only as a literal
`true`, and caps it at four tools per application - so mark the entry points
(search, summary, "what's next"), not everything.
## Functions

### Function: createStoreToolset() [#function-createstoretoolset]

```ts
function createStoreToolset(options: StoreToolsetOptions): StoreToolset;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`StoreToolsetOptions`](#interface-storetoolsetoptions) |

#### Returns

[`StoreToolset`](#interface-storetoolset)

***

### Function: deriveMcpSigningKey() [#function-derivemcpsigningkey]

```ts
function deriveMcpSigningKey(apiKey: string): string;
```

The key Connect signs your MCP requests with, from the API key you hold.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `apiKey` | `string` |

#### Returns

`string`

***

### Function: deriveStoreTools() [#function-derivestoretools]

```ts
function deriveStoreTools(options: StoreToolsetOptions): StoreTool[];
```

Every tool one declaration yields, in a stable order.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`StoreToolsetOptions`](#interface-storetoolsetoptions) |

#### Returns

[`StoreTool`](#interface-storetool)[]

***

### Function: mcpSignaturePayloadV2() [#function-mcpsignaturepayloadv2]

```ts
function mcpSignaturePayloadV2(input: McpSignaturePayloadV2Input): string;
```

The exact string `v2` is an HMAC of. Exported so a signer and a verifier can
be checked against each other byte for byte.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | [`McpSignaturePayloadV2Input`](#interface-mcpsignaturepayloadv2input) |

#### Returns

`string`

***

### Function: mcpToolMeta() [#function-mcptoolmeta]

```ts
function mcpToolMeta(options: {
  foundational?: boolean;
}): {
  _meta?: McpToolMeta;
};
```

The `_meta` field for a hand-written tool definition, to spread into it:

```ts
{ name: "search_crm", title, description, inputSchema, annotations, ...mcpToolMeta({ foundational: true }) }
```

Emits nothing when there is nothing to declare, so a definition that sets no
option is byte-for-byte what it was.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | \{ `foundational?`: `boolean`; \} |
| `options.foundational?` | `boolean` |

#### Returns

```ts
{
  _meta?: McpToolMeta;
}
```

##### \_meta?

```ts
optional _meta?: McpToolMeta;
```

***

### Function: verifyConnectMcpSignature() [#function-verifyconnectmcpsignature]

```ts
function verifyConnectMcpSignature(input: VerifyConnectMcpSignatureInput): ConnectMcpSignatureVerdict;
```

Whether a request is Connect's.

- A header carrying any `v2` is decided by `v2` alone: a `v1` beside a
  failing `v2` is not consulted, because that is exactly the shape of a
  signed request replayed with another member's bearer.
- A header with no `v2` verifies on `v1`, unless `requireV2`.
- Every candidate is compared in constant time with no early exit, so the
  time taken does not say which key matched.

Never says *why* it refused - reporting "bad timestamp" separately from
"bad signature" tells a prober which half of a forgery to keep working on.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | [`VerifyConnectMcpSignatureInput`](#type-alias-verifyconnectmcpsignatureinput) |

#### Returns

[`ConnectMcpSignatureVerdict`](#interface-connectmcpsignatureverdict)