MCP

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

Interfaces

Interface: ConnectMcpSignatureVerdict

Properties

Interface: McpSignaturePayloadV2Input

Properties

Interface: McpToolDescriptor

One entry of an MCP tools/list response.

Properties

Interface: McpToolMeta

The _meta Connect reads from a tool definition.

Indexable

[key: string]: unknown

Properties

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()

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

Parameters

Returns

Promise<StoreDocument>

query()

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

Parameters

Returns

Promise<{ items: StoreDocument[]; nextCursor: string | null; }>

aggregate()

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

Parameters

Returns

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

create()

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

Parameters

Returns

Promise<StoreDocument>

update()

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

Parameters

Returns

Promise<StoreDocument>

delete()

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

Parameters

Returns

Promise<void>

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

Methods

execute()

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

Parameters

Returns

Promise<unknown>

Interface: StoreToolset

Properties

Methods

listTools()

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

Returns

{
  tools: McpToolDescriptor[];
}

tools

tools: McpToolDescriptor[];

callTool()

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

Parameters

Returns

Promise<McpToolResult>

Interface: StoreToolsetOptions

Properties

Type Aliases

Type Alias: JsonSchema

type JsonSchema = Record<string, unknown>;

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

Type Alias: McpToolResult

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

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

type

type: "text";

text

text: string;

isError?

optional isError?: boolean;

Type Alias: StoreToolWrites

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 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

header: string | null | undefined;

The Connect-Signature header, or null when absent.

rawBody

rawBody: string;

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

method

method: string;

url

url: string | URL;

request.url, exactly as your server received it.

authorization

authorization: string | null | undefined;

The raw Authorization header value, or null when absent.

toleranceSeconds?

optional toleranceSeconds?: number;

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

requireV2?

optional requireV2?: boolean;

Refuse a header that verifies only as v1.

now?

optional now?: Date;

Variables

Variable: MCP_FOUNDATIONAL_META_KEY

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(options: StoreToolsetOptions): StoreToolset;

Parameters

Returns

StoreToolset

Function: deriveMcpSigningKey()

function deriveMcpSigningKey(apiKey: string): string;

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

Parameters

Returns

string

Function: deriveStoreTools()

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

Every tool one declaration yields, in a stable order.

Parameters

Returns

StoreTool[]

Function: mcpSignaturePayloadV2()

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

Returns

string

Function: mcpToolMeta()

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

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

{ 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

Returns

{
  _meta?: McpToolMeta;
}

_meta?

optional _meta?: McpToolMeta;

Function: verifyConnectMcpSignature()

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

Returns

ConnectMcpSignatureVerdict