@openagentid/mcp

All packages · Runnable examples · Start an agent

Entry points

• @openagentid/mcp/server
• @openagentid/mcp/client
• @openagentid/mcp/errors
• @openagentid/mcp/skills
• @openagentid/mcp/types

This reference is generated from the integrity-verified npm archive for this exact version. Signatures describe the public contract; they are not standalone programs. Complete examples are checked separately.

Import conditions

Use the public entry point above. The package resolves it to these shipped files; do not import its internal files directly.

Exports

• Agent — type
• ANONYMOUS_IDENTITY
• AuditedResultMeta — type
• AuthorizationDeniedError
• buildIdentityMeta
• combineSkillsPolicies
• createSkillsPolicy
• CreateSkillsPolicyOptions — type
• DEFAULT_SKILL_TOOL_NAMES
• defaultRequireScopes
• defaultScopeFormat
• Did — type
• ErrorHook — type
• IdentityVerificationError
• IdentityVerifier — type
• InMemorySkillsPolicyStore
• McpClientLike — type
• McpErrorCode
• McpErrorCodeValue — type
• McpServerLike — type
• MissingIdentityError
• OpenAgentClientConfig — type
• OpenAgentMcpConfig — type
• OpenAgentMcpError
• OpenAgentRequestIdentity — type
• PostCallHook — type
• PreCallHook — type
• ScopeDeriver — type
• SkillsPolicyDecision — type
• SkillsPolicyDeniedError
• SkillsPolicyHook — type
• SkillsPolicyStore — type
• SkillsRule — type
• VerifiedIdentity — type
• withOpenAgent
• withOpenAgentClient

Agent

Minimal Agent surface — only the parts of the OpenAgent SDK Agent that the MCP middleware actually needs.

Type-only declaration; it is not a runtime value.

interface Agent {
    did: Did;
    verifier: IdentityVerifier;
    signRequest(toolName: string, audience?: Did): Promise<OpenAgentRequestIdentity>;
}

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:69.

ANONYMOUS_IDENTITY

declare const ANONYMOUS_IDENTITY: VerifiedIdentity;

Source: @openagentid/mcp@0.1.1, dist/server.d.ts:64.

AuditedResultMeta

Result envelope returned by an authenticated tool call. The auditId is pushed into _meta.openagent.audit_id on the response, so callers can correlate logs end-to-end.

Type-only declaration; it is not a runtime value.

interface AuditedResultMeta {
    audit_id: string;
    verified_did: Did;
    scopes: ReadonlyArray<string>;
}

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:83.

AuthorizationDeniedError

Caller's verified identity does not hold the required scopes.

declare class AuthorizationDeniedError extends OpenAgentMcpError {
    constructor(toolName: string, requiredScopes: ReadonlyArray<string>, heldScopes: ReadonlyArray<string>);
}

Source: @openagentid/mcp@0.1.1, dist/errors.d.ts:56.

buildIdentityMeta

Helper for tests and tools that want to construct the identity envelope manually without going through a full Agent. Returns a _meta object that can be merged into a CallToolRequest's params.

declare function buildIdentityMeta(identity: {
    did: string;
    proof: string;
    nonce?: string;
    context?: Record<string, unknown>;
}): Record<string, unknown>;

Source: @openagentid/mcp@0.1.1, dist/client.d.ts:75.

combineSkillsPolicies

Compose two skills policy hooks. The combined hook denies if either underlying hook denies; allow decisions from first are forwarded to second.

declare function combineSkillsPolicies(first: SkillsPolicyHook, second: SkillsPolicyHook): SkillsPolicyHook;

Source: @openagentid/mcp@0.1.1, dist/skills.d.ts:85.

createSkillsPolicy

Build a {@link SkillsPolicyHook} from a store and matching options.

The returned hook always allows tools that are not skill-like; it only consults the store when {@link CreateSkillsPolicyOptions.isSkillTool} returns true.

declare function createSkillsPolicy(options: CreateSkillsPolicyOptions): SkillsPolicyHook;

Source: @openagentid/mcp@0.1.1, dist/skills.d.ts:79.

CreateSkillsPolicyOptions

Type-only declaration; it is not a runtime value.

interface CreateSkillsPolicyOptions {
    store: SkillsPolicyStore;
    isSkillTool?: (toolName: string) => boolean;
    extractSkillName?: (args: unknown) => string | null;
    defaultDecision?: SkillsPolicyDecision;
}

Source: @openagentid/mcp@0.1.1, dist/skills.d.ts:52.

DEFAULT_SKILL_TOOL_NAMES

Tool name prefixes that the middleware treats as skill-like by default. Host applications can override the matcher entirely via {@link createSkillsPolicy}.

declare const DEFAULT_SKILL_TOOL_NAMES: ReadonlyArray<string>;

Source: @openagentid/mcp@0.1.1, dist/skills.d.ts:21.

defaultRequireScopes

Default scope deriver used when {@link OpenAgentMcpConfig.requireScopes} is not supplied.

declare const defaultRequireScopes: (toolName: string) => ReadonlyArray<string>;

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:177.

defaultScopeFormat

Default scope format used when {@link OpenAgentMcpConfig.scopeFormat} is not supplied.

declare const defaultScopeFormat: (toolName: string) => string;

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:172.

Did

A decentralized identifier following the did:oas:* method or any other DID method understood by the configured verifier.

Type-only declaration; it is not a runtime value.

type Did = string;

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:17.

ErrorHook

Hook fired when the tool body or any earlier middleware step throws. The middleware re-throws the error after running this hook so MCP clients still observe the original failure mode.

Type-only declaration; it is not a runtime value.

type ErrorHook = (input: {
    toolName: string;
    args: unknown;
    identity: VerifiedIdentity | null;
    error: unknown;
}) => Promise<void> | void;

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:130.

IdentityVerificationError

Identity envelope was present but the verifier rejected it.

declare class IdentityVerificationError extends OpenAgentMcpError {
    constructor(toolName: string, cause: unknown);
}

Source: @openagentid/mcp@0.1.1, dist/errors.d.ts:52.

IdentityVerifier

The verifier interface — implemented by @openagentid/sdk (production) and by the in-memory test agent shipped here.

Implementations MUST be deterministic for a given input and MUST NOT mutate the request identity object.

Type-only declaration; it is not a runtime value.

interface IdentityVerifier {
    verify(identity: OpenAgentRequestIdentity, requiredScopes: ReadonlyArray<string>): Promise<VerifiedIdentity>;
}

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:62.

InMemorySkillsPolicyStore

Trivial in-memory store useful in tests and as a starting point for production stores.

declare class InMemorySkillsPolicyStore implements SkillsPolicyStore {
    constructor(rules?: ReadonlyArray<SkillsRule>);
    lookup(skillName: string): SkillsRule | null;
    withRule(rule: SkillsRule): InMemorySkillsPolicyStore;
}

Source: @openagentid/mcp@0.1.1, dist/skills.d.ts:45.

McpClientLike

Minimal MCP client surface used by the interceptor. Like the server adapter, we describe just the methods we need to keep peer-dep compatibility broad.

Type-only declaration; it is not a runtime value.

interface McpClientLike {
    callTool(params: {
        name: string;
        arguments?: Record<string, unknown>;
        _meta?: Record<string, unknown>;
    }, ...rest: unknown[]): Promise<unknown>;
}

Source: @openagentid/mcp@0.1.1, dist/client.d.ts:30.

McpErrorCode

Standard JSON-RPC + MCP error codes used by the middleware.

declare const McpErrorCode: {
    readonly InvalidRequest: -32600;
    readonly MethodNotFound: -32601;
    readonly InvalidParams: -32602;
    readonly InternalError: -32603;
    readonly ServerError: -32000;
    readonly AuthenticationFailed: -32001;
    readonly AuthorizationDenied: -32002;
    readonly SkillsPolicyDenied: -32003;
};

Source: @openagentid/mcp@0.1.1, dist/errors.d.ts:10.

McpErrorCodeValue

Type-only declaration; it is not a runtime value.

type McpErrorCodeValue = (typeof McpErrorCode)[keyof typeof McpErrorCode];

Source: @openagentid/mcp@0.1.1, dist/errors.d.ts:28.

McpServerLike

Minimal McpServer surface used by the middleware. We avoid importing concrete types from @modelcontextprotocol/sdk because peer-dep versions vary across host applications and the SDK's own type exports are subject to change. The shape below is the intersection of every 1.x McpServer release.

Type-only declaration; it is not a runtime value.

interface McpServerLike {
    tool(...args: unknown[]): unknown;
    registerTool(...args: unknown[]): unknown;
}

Source: @openagentid/mcp@0.1.1, dist/server.d.ts:39.

MissingIdentityError

Caller did not present an OpenAgent identity envelope.

declare class MissingIdentityError extends OpenAgentMcpError {
    constructor(toolName: string);
}

Source: @openagentid/mcp@0.1.1, dist/errors.d.ts:48.

OpenAgentClientConfig

Type-only declaration; it is not a runtime value.

interface OpenAgentClientConfig {
    agent: Agent;
    audience?: string;
    beforeCall?: (params: {
        name: string;
        arguments?: Record<string, unknown>;
        _meta?: Record<string, unknown>;
    }) => Promise<{
        name: string;
        arguments?: Record<string, unknown>;
        _meta?: Record<string, unknown>;
    } | void> | {
        name: string;
        arguments?: Record<string, unknown>;
        _meta?: Record<string, unknown>;
    } | void;
}

Source: @openagentid/mcp@0.1.1, dist/client.d.ts:37.

OpenAgentMcpConfig

Configuration for {@link withOpenAgent }.

Type-only declaration; it is not a runtime value.

interface OpenAgentMcpConfig {
    agent: Agent;
    requireScopes?: ScopeDeriver;
    requireIdentity?: boolean;
    skillsPolicy?: SkillsPolicyHook;
    preCall?: PreCallHook;
    postCall?: PostCallHook;
    onError?: ErrorHook;
    scopeFormat?: (toolName: string) => string;
}

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:139.

OpenAgentMcpError

Base class for all middleware errors. Subclasses set a default {@link OpenAgentMcpError.code} that maps to a JSON-RPC error code.

declare class OpenAgentMcpError extends Error {
    readonly code: McpErrorCodeValue;
    readonly data?: Record<string, unknown>;
    constructor(message: string, code: McpErrorCodeValue, data?: Record<string, unknown>);
    toJsonRpcError(): {
        code: McpErrorCodeValue;
        message: string;
        data?: Record<string, unknown>;
    };
}

Source: @openagentid/mcp@0.1.1, dist/errors.d.ts:33.

OpenAgentRequestIdentity

The four pieces of metadata an MCP request carries about the calling agent. Populated by the {@link createClientInterceptor } on the call site and consumed by the server middleware.

Type-only declaration; it is not a runtime value.

interface OpenAgentRequestIdentity {
    did: Did;
    proof: string;
    nonce?: string;
    context?: Record<string, unknown>;
}

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:23.

PostCallHook

Hook fired after a tool body executes successfully. Use it for audit logging, metrics, and trace propagation. Throwing from this hook does NOT roll back the tool call.

Type-only declaration; it is not a runtime value.

type PostCallHook = (input: {
    toolName: string;
    args: unknown;
    identity: VerifiedIdentity;
    durationMs: number;
    result: unknown;
}) => Promise<void> | void;

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:118.

PreCallHook

Hook fired before a tool body executes — after the identity has been verified and the skills policy has approved the call.

Type-only declaration; it is not a runtime value.

type PreCallHook = (input: {
    toolName: string;
    args: unknown;
    identity: VerifiedIdentity;
}) => Promise<void> | void;

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:108.

ScopeDeriver

Per-tool scope deriver.

Type-only declaration; it is not a runtime value.

type ScopeDeriver = (toolName: string, args: unknown) => ReadonlyArray<string>;

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:89.

SkillsPolicyDecision

Type-only declaration; it is not a runtime value.

interface SkillsPolicyDecision {
    allow: boolean;
    reason?: string;
}

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:100.

SkillsPolicyDeniedError

Skills policy hook returned allow: false.

declare class SkillsPolicyDeniedError extends OpenAgentMcpError {
    constructor(toolName: string, reason: string | undefined);
}

Source: @openagentid/mcp@0.1.1, dist/errors.d.ts:60.

SkillsPolicyHook

Hook signature for the skills policy. The hook receives the tool name, the arguments, and the verified identity, and decides whether the call should be allowed.

Type-only declaration; it is not a runtime value.

type SkillsPolicyHook = (input: {
    toolName: string;
    args: unknown;
    identity: VerifiedIdentity;
}) => Promise<SkillsPolicyDecision> | SkillsPolicyDecision;

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:95.

SkillsPolicyStore

Policy store interface — implementations may be in-memory, file-backed by SKILLS.md, or fetched from a remote service.

Type-only declaration; it is not a runtime value.

interface SkillsPolicyStore {
    lookup(skillName: string): Promise<SkillsRule | null> | SkillsRule | null;
}

Source: @openagentid/mcp@0.1.1, dist/skills.d.ts:38.

SkillsRule

A single rule describing whether a (skillName, did) pair is allowed. null for dids means "any verified caller". An empty array means "no caller".

Type-only declaration; it is not a runtime value.

interface SkillsRule {
    skillName: string;
    dids: ReadonlyArray<string> | null;
    reason?: string;
}

Source: @openagentid/mcp@0.1.1, dist/skills.d.ts:27.

VerifiedIdentity

The result of running the auth pipeline against an incoming MCP request. Available to post-call hooks and audit log emitters.

Type-only declaration; it is not a runtime value.

interface VerifiedIdentity {
    did: Did;
    scopes: ReadonlyArray<string>;
    auditId: string;
    claims: Readonly<Record<string, unknown>>;
}

Source: @openagentid/mcp@0.1.1, dist/types.d.ts:47.

withOpenAgent

Wrap an MCP server so every tool call is authenticated against an OpenAgent identity.

declare function withOpenAgent<T extends McpServerLike>(server: T, config: OpenAgentMcpConfig): T;

Source: @openagentid/mcp@0.1.1, dist/server.d.ts:63.

withOpenAgentClient

Wrap an MCP client so every outbound callTool carries an OpenAgent identity envelope.

declare function withOpenAgentClient<T extends McpClientLike>(client: T, config: OpenAgentClientConfig): T;

Source: @openagentid/mcp@0.1.1, dist/client.d.ts:69.

Package requirements

Peer dependencies

Archive verification

Pinned integrity:

sha512-Kquw9MiLgfnmX5w7RK3FK1SYKcexe5wKJk8DtlOnEaN8k/0Z+WytXkEFWwj+W4+E9ug708jwfKHFlAjdNYSUWA==

Machine-readable API manifest · Coverage