Interface AdcpServer

Optional Readonly[ADCP_SERVER_BRAND]

Readonlycompliance

connect

• connect(transport: AdcpServerTransport): Promise<void>

  Connect the server to an MCP transport.

  Takes ownership of the transport — any callbacks previously registered on it are replaced. Matches the semantics of the SDK's McpServer.connect().

  Parameters

  • transport: AdcpServerTransport

  Returns Promise<void>

close

• close(): Promise<void>

  Close the server and release resources.

  Returns Promise<void>

dispatchTestRequest

• dispatchTestRequest(
      request: AdcpTestToolsCallRequest,
      extras?: AdcpTestRequestExtras,
  ): Promise<
      {
          _meta?: {
              progressToken?: string
              | number;
              "io.modelcontextprotocol/related-task"?: { taskId: string };
              [key: string]: unknown;
          };
          content: (
              | {
                  type: "text";
                  text: string;
                  annotations?: {
                      audience?: ("user" | "assistant")[];
                      priority?: number;
                      lastModified?: string;
                  };
                  _meta?: { [key: string]: unknown };
              }
              | {
                  type: "image";
                  data: string;
                  mimeType: string;
                  annotations?: {
                      audience?: ("user" | "assistant")[];
                      priority?: number;
                      lastModified?: string;
                  };
                  _meta?: { [key: string]: unknown };
              }
              | {
                  type: "audio";
                  data: string;
                  mimeType: string;
                  annotations?: {
                      audience?: ("user" | "assistant")[];
                      priority?: number;
                      lastModified?: string;
                  };
                  _meta?: { [key: string]: unknown };
              }
              | {
                  uri: string;
                  description?: string;
                  mimeType?: string;
                  size?: number;
                  annotations?: {
                      audience?: ("user" | "assistant")[];
                      priority?: number;
                      lastModified?: string;
                  };
                  _meta?: { [key: string]: unknown };
                  icons?: {
                      src: string;
                      mimeType?: string;
                      sizes?: string[];
                      theme?: "light" | "dark";
                  }[];
                  name: string;
                  title?: string;
                  type: "resource_link";
              }
              | {
                  type: "resource";
                  resource: | {
                      uri: string;
                      mimeType?: string;
                      _meta?: { [key: string]: unknown };
                      text: string;
                  }
                  | {
                      uri: string;
                      mimeType?: string;
                      _meta?: { [key: string]: unknown };
                      blob: string;
                  };
                  annotations?: {
                      audience?: ("user" | "assistant")[];
                      priority?: number;
                      lastModified?: string;
                  };
                  _meta?: { [key: string]: unknown };
              }
          )[];
          structuredContent?: { [key: string]: unknown };
          isError?: boolean;
          [key: string]: unknown;
      },
  >

  Invoke a registered handler in-process and return its response.

  Bypasses the transport layer — no sockets, no JSON-RPC framing. Intended for test harnesses only; production callers should go through a transport so protocol invariants (request ID linking, task progress, notifications) are enforced.

  Throws when no handler is registered for the requested method, or when a tools/call request targets an unknown tool. Arguments default to {} when params.arguments is omitted — a validation error from the tool's input schema (not from dispatch) is the expected failure mode for a missing required field.

  Never mount this behind an HTTP route. extras.authInfo is written directly onto the MCP handler's extra without any check against serve({ authenticate }) — exposing it externally lets a caller impersonate any principal. This API is for in-process test harnesses and storyboard runners only.

  Parameters

  • request: AdcpTestToolsCallRequest
  • Optionalextras: AdcpTestRequestExtras

  Returns Promise<
      {
          _meta?: {
              progressToken?: string
              | number;
              "io.modelcontextprotocol/related-task"?: { taskId: string };
              [key: string]: unknown;
          };
          content: (
              | {
                  type: "text";
                  text: string;
                  annotations?: {
                      audience?: ("user" | "assistant")[];
                      priority?: number;
                      lastModified?: string;
                  };
                  _meta?: { [key: string]: unknown };
              }
              | {
                  type: "image";
                  data: string;
                  mimeType: string;
                  annotations?: {
                      audience?: ("user" | "assistant")[];
                      priority?: number;
                      lastModified?: string;
                  };
                  _meta?: { [key: string]: unknown };
              }
              | {
                  type: "audio";
                  data: string;
                  mimeType: string;
                  annotations?: {
                      audience?: ("user" | "assistant")[];
                      priority?: number;
                      lastModified?: string;
                  };
                  _meta?: { [key: string]: unknown };
              }
              | {
                  uri: string;
                  description?: string;
                  mimeType?: string;
                  size?: number;
                  annotations?: {
                      audience?: ("user" | "assistant")[];
                      priority?: number;
                      lastModified?: string;
                  };
                  _meta?: { [key: string]: unknown };
                  icons?: {
                      src: string;
                      mimeType?: string;
                      sizes?: string[];
                      theme?: "light" | "dark";
                  }[];
                  name: string;
                  title?: string;
                  type: "resource_link";
              }
              | {
                  type: "resource";
                  resource: | {
                      uri: string;
                      mimeType?: string;
                      _meta?: { [key: string]: unknown };
                      text: string;
                  }
                  | {
                      uri: string;
                      mimeType?: string;
                      _meta?: { [key: string]: unknown };
                      blob: string;
                  };
                  annotations?: {
                      audience?: ("user" | "assistant")[];
                      priority?: number;
                      lastModified?: string;
                  };
                  _meta?: { [key: string]: unknown };
              }
          )[];
          structuredContent?: { [key: string]: unknown };
          isError?: boolean;
          [key: string]: unknown;
      },
  >

  Example

  const result = await server.dispatchTestRequest({
    method: 'tools/call',
    params: {
      name: 'get_products',
      arguments: { brief: 'premium sports inventory' },
    },
  });
  Copy

• dispatchTestRequest(
      request: AdcpTestRequest,
      extras?: AdcpTestRequestExtras,
  ): Promise<unknown>

  Parameters

  • request: AdcpTestRequest
  • Optionalextras: AdcpTestRequestExtras

  Returns Promise<unknown>

invoke

• invoke(options: AdcpInvokeOptions): Promise<McpToolResponse>

  Production-safe tool invocation surface for transport adapters.

  Runs the full framework pipeline against a registered tool: request schema validation → account resolution → idempotency → handler dispatch → response narrowing → response validation. Returns the same McpToolResponse envelope the MCP transport observes — a transport adapter layers its own protocol framing on top (JSON-RPC result for MCP, A2A Task artifact for A2A, etc.).

  Auth is the caller's responsibility. invoke() forwards the provided authInfo verbatim to handlers and resolveAccount without re-verifying. Mount it only behind a transport that has already authenticated the principal (e.g. serve({ authenticate }) for MCP, createA2AAdapter({ authenticate }) for A2A). Do not call it directly from an HTTP handler — that path skips auth.

  For in-process tests that want to synthesize an authInfo without running a transport, reach for dispatchTestRequest instead — it takes the same principal shape but is explicitly marked test-only in its docstring.

  Throws when toolName is not registered; schema errors round-trip as structured VALIDATION_ERROR envelopes inside the return value.

  Parameters

  • options: AdcpInvokeOptions

  Returns Promise<McpToolResponse>

getAdcpVersion

• getAdcpVersion(): string

  Returns the AdCP protocol version this server is configured to speak.

  Defaults to ADCP_VERSION (the GA version the SDK ships against) unless overridden via createAdcpServer({ adcpVersion }). This is the protocol version, not the publisher's app version (config.version).

  Plumbing surface — Stage 2 of the multi-version refactor exposes the configured value but does not yet vary validator/schema selection by version. Wire-shape adapters key off this getter in subsequent stages.

  Returns string