sello 0.1.13 → 0.1.15

package/README.md

@@ -16,6 +16,7 @@
 <p align="center">
   <a href="#try-it">Quickstart</a> &middot;
   <a href="#add-sello-to-a-tool">Add Sello</a> &middot;
+  <a href="#add-sello-to-an-mcp-server">MCP</a> &middot;
   <a href="sdks/README.md">SDKs</a> &middot;
   <a href="#see-logged-actions">Actions</a> &middot;
   <a href="#how-it-works">How It Works</a> &middot;
@@ -116,6 +117,39 @@ npx --yes sello init-demo
 npx --yes sello init-http-demo
 ```
 
+## Add Sello to an MCP Server
+
+If your service exposes MCP tools, wrap the tool callback:
+
+```ts
+import { sello } from "sello";
+
+const receipts = sello.service();
+
+server.registerTool(
+  "calendar.create_event",
+  { inputSchema: createEventInputSchema },
+  receipts.mcpTool("calendar.create_event", async (args) => {
+    const event = await calendar.events.create(args);
+    return {
+      content: [{ type: "text", text: event.id }],
+    };
+  }),
+);
+```
+
+Some MCP SDK versions call this method `tool` instead of `registerTool`; use the same callback slot either way.
+
+`mcpTool` verifies the agent token before your callback runs, preserves the callback's return value, rethrows callback errors, and emits a receipt with action type `mcp.tools/call.<tool-name>`.
+
+By default, Sello looks for an `Authorization: Bearer ...` token in common MCP context/header fields. If your transport stores tokens somewhere else, pass an extractor:
+
+```ts
+receipts.mcpTool("calendar.create_event", handler, {
+  authorizationToken: ({ context }) => context.session.token,
+});
+```
+
 ## See Logged Actions
 
 ```bash
@@ -155,7 +189,7 @@ Sello does not prove that the agent called every service it should have called,
 - [Protocol Walkthrough](docs/protocol-walkthrough.md): the primitive receipt loop for implementers.
 - [SPEC.md](SPEC.md): the Sello protocol draft.
 - [Notarized Agents paper](https://arxiv.org/abs/2606.04193): design rationale, threat model, and prior art.
-- [sdks/typescript/examples/mcp-minimal-server.ts](sdks/typescript/examples/mcp-minimal-server.ts): a small MCP-shaped integration.
+- [sdks/typescript/examples/mcp-minimal-server.ts](sdks/typescript/examples/mcp-minimal-server.ts): a small MCP integration.
 - [docs/security-review.md](docs/security-review.md) and [docs/sdk-security-audit.md](docs/sdk-security-audit.md): current review notes.
 
 The TypeScript SDK is published on [npm](https://www.npmjs.com/package/sello) and lives in [`sdks/typescript/`](sdks/typescript/). The Python SDK is published on [PyPI](https://pypi.org/project/sello/) and lives in [`sdks/python/`](sdks/python/). Both SDKs support the same service-side `sello.service()` flow; Python uses the `@receipts.tool(...)` decorator. Live Rekor proof verification and production identity operations are still future work.

package/dist/cli/sello.js

@@ -199,6 +199,29 @@ async function devCommand(args          )                {
     console.log(`Local dev log: ${logPath}`);
     console.log(`Loaded ${devLogEntryCountLabel(loadedEntries)}.`);
   });
+  server.on("error", (error) => {
+    if (isPortInUse(error)) {
+      console.error(`sello: port ${port} is already in use.`);
+      console.error("");
+      console.error("Try:");
+      console.error(`  sello dev --port ${port + 1}`);
+      console.error("");
+      console.error("Or stop the process using that port:");
+      console.error(`  lsof -nP -iTCP:${port} -sTCP:LISTEN`);
+      process.exitCode = 1;
+      return;
+    }
+
+    if (isListenError(error)) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`sello: could not start dev server on port ${port}.`);
+      console.error(message);
+      process.exitCode = 1;
+      return;
+    }
+
+    throw error;
+  });
 }
 
 async function emitDemoCommand(args          )                {
@@ -257,14 +280,7 @@ async function callHttpDemoCommand(args          )                {
   );
   const url = readFlag(args, "--url") ?? "http://localhost:8790/calendar/events";
   const title = readFlag(args, "--title") ?? "Ship Sello";
-  const response = await fetch(url, {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${state.agentToken}`,
-      "content-type": "application/json",
-    },
-    body: JSON.stringify({ title }),
-  });
+  const response = await fetchHttpDemo(url, state.agentToken, title);
   const responseText = await response.text();
 
   if (!response.ok) {
@@ -283,6 +299,31 @@ async function callHttpDemoCommand(args          )                {
   console.log(`  ${actionViewerUrl(state)}`);
 }
 
+async function fetchHttpDemo(
+  url        ,
+  agentToken        ,
+  title        ,
+)                    {
+  try {
+    return await fetch(url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${agentToken}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ title }),
+    });
+  } catch (error) {
+    if (isFetchFailed(error)) {
+      throw new TypeError(
+        `could not reach the HTTP demo route at ${url}.\n\nStart it in another terminal:\n  node sello-http-route.mjs`,
+      );
+    }
+
+    throw error;
+  }
+}
+
 function initDemoCommand(args          )       {
   const output = readFlag(args, "--output") ?? "emit-receipt.mjs";
   const force = args.includes("--force");
@@ -787,6 +828,22 @@ function isRecord(value         )                                   {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function isPortInUse(error         )          {
+  return (
+    isRecord(error) &&
+    error.code === "EADDRINUSE" &&
+    error.syscall === "listen"
+  );
+}
+
+function isListenError(error         )          {
+  return isRecord(error) && error.syscall === "listen";
+}
+
+function isFetchFailed(error         )          {
+  return error instanceof TypeError && error.message === "fetch failed";
+}
+
 function printHelp()       {
   console.log(`Usage:
   sello dev [--port 8787] [--service service-id] [--dry-run]

package/dist/sdk/service.js

@@ -41,6 +41,36 @@ import {
                                                                       
   
 
+                                                               
+               
+                  
+                   
+  
+
+                                                                      
+             
+                   
+                                  
+
+                                                                      
+                      
+                                          
+                                          
+                       
+    
+                       
+                                                      
+                  
+                                                          
+                                                     
+              
+                                                      
+                                  
+                    
+                                                      
+                                    
+  
+
                                   
                    
                                
@@ -65,6 +95,11 @@ import {
                                                  
                                                   
                                          
+                                             
+                 
+                                                          
+                                                           
+                                                  
                          
   
 
@@ -114,90 +149,126 @@ export function createSelloService(input                    )                {
     return publisher;
   }
 
-  return {
-    tool                   (
-      actionType        ,
-      handler                                     ,
-      options                                      = {},
-    )                                      {
-      if (typeof actionType !== "string" || actionType.length === 0) {
-        throw new TypeError("Sello action type must be a non-empty string");
-      }
+  function wrapTool                   (
+    actionType        ,
+    handler                                     ,
+    options                                      = {},
+  )                                      {
+    if (typeof actionType !== "string" || actionType.length === 0) {
+      throw new TypeError("Sello action type must be a non-empty string");
+    }
 
-      return async (request         )                    => {
-        const resolved = await config();
-        const authorizationToken = resolveValue(
-          options.authorizationToken ?? defaultAuthorizationToken,
-          request,
-        );
-        const tokenIssuerPublicKey = await resolveTokenIssuerPublicKey(resolved.tokenIssuer);
-        const verifiedToken = verifySelloJwsToken({
-          authorizationToken,
-          issuerPublicKey: tokenIssuerPublicKey,
+    return async (request         )                    => {
+      const resolved = await config();
+      const authorizationToken = resolveValue(
+        options.authorizationToken ?? defaultAuthorizationToken,
+        request,
+      );
+      const tokenIssuerPublicKey = await resolveTokenIssuerPublicKey(resolved.tokenIssuer);
+      const verifiedToken = verifySelloJwsToken({
+        authorizationToken,
+        issuerPublicKey: tokenIssuerPublicKey,
+      });
+      const selloLogs = selectSelloLogs(
+        verifiedToken.selloLogs,
+        resolved.fallbackSelloLogs,
+        resolved.log.logUrl,
+      );
+      const base = {
+        authorizationTokenBytes: verifiedToken.authorizationTokenBytes,
+        ownerHpkePublicKey: verifiedToken.ownerHpkePublicKey,
+        selloLogs,
+        serviceKid: resolved.serviceKid,
+        servicePrivateKey: resolved.servicePrivateKey,
+        serviceIdentifier: resolved.service,
+        logUrl: resolved.log.logUrl,
+        actionType,
+        actionInputBytes: (options.canonicalizeInput ?? canonicalJsonBytes)(request),
+        timestamp: resolved.now(),
+      };
+
+      if (options.isDenied && (await options.isDenied(request))) {
+        const response = options.deniedResponse
+          ? await options.deniedResponse(request)
+          : undefined;
+        const receipt = emitReceipt({
+          ...base,
+          actionOutputBytes: new Uint8Array(),
+          resultStatus: "denied",
         });
-        const selloLogs = selectSelloLogs(
-          verifiedToken.selloLogs,
-          resolved.fallbackSelloLogs,
-          resolved.log.logUrl,
-        );
-        const base = {
-          authorizationTokenBytes: verifiedToken.authorizationTokenBytes,
-          ownerHpkePublicKey: verifiedToken.ownerHpkePublicKey,
-          selloLogs,
-          serviceKid: resolved.serviceKid,
-          servicePrivateKey: resolved.servicePrivateKey,
-          serviceIdentifier: resolved.service,
-          logUrl: resolved.log.logUrl,
-          actionType,
-          actionInputBytes: (options.canonicalizeInput ?? canonicalJsonBytes)(request),
-          timestamp: resolved.now(),
-        };
-
-        if (options.isDenied && (await options.isDenied(request))) {
-          const response = options.deniedResponse
-            ? await options.deniedResponse(request)
-            : undefined;
-          const receipt = emitReceipt({
-            ...base,
-            actionOutputBytes: new Uint8Array(),
-            resultStatus: "denied",
-          });
-          resolved.onReceipt?.({ resultStatus: "denied", receipt, response });
-          await submit(resolved, receipt, base.timestamp);
-
-          if (options.deniedResponse) {
-            return response            ;
-          }
-
-          throw new SelloDeniedError(receipt);
-        }
+        resolved.onReceipt?.({ resultStatus: "denied", receipt, response });
+        await submit(resolved, receipt, base.timestamp);
 
-        let response          ;
-        try {
-          response = await handler(request);
-        } catch (error) {
-          const receipt = emitReceipt({
-            ...base,
-            actionOutputBytes: (options.canonicalizeError ?? canonicalErrorBytes)(
-              error,
-            ),
-            resultStatus: "error",
-          });
-          resolved.onReceipt?.({ resultStatus: "error", receipt, error });
-          await submit(resolved, receipt, base.timestamp);
-          throw error;
+        if (options.deniedResponse) {
+          return response            ;
         }
 
+        throw new SelloDeniedError(receipt);
+      }
+
+      let response          ;
+      try {
+        response = await handler(request);
+      } catch (error) {
         const receipt = emitReceipt({
           ...base,
-          actionOutputBytes: (options.canonicalizeOutput ?? canonicalJsonBytes)(
-            response,
+          actionOutputBytes: (options.canonicalizeError ?? canonicalErrorBytes)(
+            error,
           ),
-          resultStatus: "success",
+          resultStatus: "error",
         });
-        resolved.onReceipt?.({ resultStatus: "success", receipt, response });
+        resolved.onReceipt?.({ resultStatus: "error", receipt, error });
         await submit(resolved, receipt, base.timestamp);
-        return response;
+        throw error;
+      }
+
+      const receipt = emitReceipt({
+        ...base,
+        actionOutputBytes: (options.canonicalizeOutput ?? canonicalJsonBytes)(
+          response,
+        ),
+        resultStatus: "success",
+      });
+      resolved.onReceipt?.({ resultStatus: "success", receipt, response });
+      await submit(resolved, receipt, base.timestamp);
+      return response;
+    };
+  }
+
+  return {
+    tool                   (
+      actionType        ,
+      handler                                     ,
+      options                                      = {},
+    )                                      {
+      return wrapTool(actionType, handler, options);
+    },
+    mcpTool                                   (
+      name        ,
+      handler                                              ,
+      options                                               = {},
+    )                                               {
+      if (typeof name !== "string" || name.length === 0) {
+        throw new TypeError("MCP tool name must be a non-empty string");
+      }
+
+      const wrapped = wrapTool                                                 (
+        options.actionType ?? `mcp.tools/call.${name}`,
+        async (invocation) => handler(invocation.arguments, invocation.context),
+        {
+          authorizationToken:
+            options.authorizationToken ?? defaultMcpAuthorizationToken,
+          canonicalizeInput:
+            options.canonicalizeInput ?? defaultMcpCanonicalizeInput,
+          canonicalizeOutput: options.canonicalizeOutput,
+          canonicalizeError: options.canonicalizeError,
+          isDenied: options.isDenied,
+          deniedResponse: options.deniedResponse,
+        },
+      );
+
+      return async (args      , context         )                    => {
+        return await wrapped({ name, arguments: args, context });
       };
     },
     async flush()                {
@@ -481,23 +552,113 @@ function selectSelloLogs(
 }
 
 function defaultAuthorizationToken(request         )                      {
+  const token = authorizationTokenFromUnknown(request);
+  if (token) {
+    return token;
+  }
+
+  throw new TypeError(
+    "Sello authorization token not found. Pass authorizationToken or include request.authorizationToken.",
+  );
+}
+
+function defaultMcpAuthorizationToken(
+  invocation                                          ,
+)                      {
+  const fromContext = authorizationTokenFromUnknown(invocation.context);
+  if (fromContext) {
+    return fromContext;
+  }
+
+  throw new TypeError(
+    "Sello MCP authorization token not found. Pass authorizationToken or include an Authorization header in the MCP context.",
+  );
+}
+
+function defaultMcpCanonicalizeInput(
+  invocation                                          ,
+)             {
+  return canonicalJsonBytes({
+    method: "tools/call",
+    params: {
+      name: invocation.name,
+      arguments: invocation.arguments,
+    },
+  });
+}
+
+function authorizationTokenFromUnknown(value         )                                  {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const direct = value.authorizationToken ?? value.authorization;
+  if (typeof direct === "string" || direct instanceof Uint8Array) {
+    return stripBearer(direct);
+  }
+
+  const headers = value.headers;
+  const fromHeaders = authorizationTokenFromHeaders(headers);
+  if (fromHeaders) {
+    return fromHeaders;
+  }
+
+  const requestInfo = value.requestInfo;
+  if (isRecord(requestInfo)) {
+    const fromRequestInfo = authorizationTokenFromHeaders(requestInfo.headers);
+    if (fromRequestInfo) {
+      return fromRequestInfo;
+    }
+  }
+
+  const request = value.request;
   if (isRecord(request)) {
-    const direct = request.authorizationToken ?? request.authorization;
-    if (typeof direct === "string" || direct instanceof Uint8Array) {
-      return stripBearer(direct);
+    const fromRequest = authorizationTokenFromHeaders(request.headers);
+    if (fromRequest) {
+      return fromRequest;
     }
+  }
 
-    const headers = request.headers;
-    if (isRecord(headers)) {
-      const header = headers.authorization ?? headers.Authorization;
-      if (typeof header === "string") {
-        return stripBearer(header);
-      }
+  const authInfo = value.authInfo;
+  if (isRecord(authInfo)) {
+    const token = authInfo.token ?? authInfo.accessToken ?? authInfo.access_token;
+    if (typeof token === "string" || token instanceof Uint8Array) {
+      return stripBearer(token);
     }
   }
 
-  throw new TypeError(
-    "Sello authorization token not found. Pass authorizationToken or include request.authorizationToken.",
+  return undefined;
+}
+
+function authorizationTokenFromHeaders(
+  headers         ,
+)                                  {
+  if (isHeadersLike(headers)) {
+    const header = headers.get("authorization") ?? headers.get("Authorization");
+    if (typeof header === "string") {
+      return stripBearer(header);
+    }
+  }
+
+  if (!isRecord(headers)) {
+    return undefined;
+  }
+
+  const header = headers.authorization ?? headers.Authorization;
+  if (typeof header === "string" || header instanceof Uint8Array) {
+    return stripBearer(header);
+  }
+
+  return undefined;
+}
+
+function isHeadersLike(
+  value         ,
+)                                                {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value                     ).get === "function"
   );
 }
 

package/docs/sdk-quickstart.md

@@ -97,6 +97,35 @@ node --run example:tool
 node --run actions
 ```
 
+For an MCP tool, wrap the callback you already register:
+
+```ts
+import { sello } from "sello";
+
+const receipts = sello.service();
+
+server.registerTool(
+  "calendar.create_event",
+  { inputSchema: createEventInputSchema },
+  receipts.mcpTool("calendar.create_event", async (args) => {
+    const event = await calendar.events.create(args);
+    return {
+      content: [{ type: "text", text: event.id }],
+    };
+  }),
+);
+```
+
+Some MCP SDK versions call this method `tool` instead of `registerTool`; use the same callback slot either way.
+
+`receipts.mcpTool(...)` uses action type `mcp.tools/call.<tool-name>` and hashes only the MCP method name, tool name, and arguments. It tries common MCP context/header locations for the bearer token. If your transport puts the token somewhere else, pass an extractor:
+
+```ts
+receipts.mcpTool("calendar.create_event", handler, {
+  authorizationToken: ({ context }) => context.session.token,
+});
+```
+
 Or run the matching Python example:
 
 ```bash

package/docs/sdk-security-audit.md

@@ -29,6 +29,7 @@ These notes cover the first Stripe-style SDK implementation pass. They are writt
 - Invalid tokens prevent the handler from running and emit no receipt.
 - Success, error, and denied paths emit receipts without including plaintext request or response bodies.
 - The wrapper uses the configured service identity and key for every receipt.
+- `receipts.mcpTool(...)` reuses the same wrapper path. It defaults to hashing the MCP `tools/call` method, tool name, and arguments, while excluding bearer tokens and transport context from the action input hash.
 
 ## Phase 4: Logs And Action Viewing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sello",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Reference implementation of the Sello protocol for service-signed AI agent receipts.",
   "type": "module",
   "license": "Apache-2.0",

package/sdks/typescript/examples/mcp-minimal-server.ts

@@ -1,8 +1,4 @@
-import {
-  canonicalJsonBytes,
-  sello,
-  type SelloReceipts,
-} from "../src/index.ts";
+import { sello, type SelloReceipts } from "../src/index.ts";
 
 export type MinimalMcpRequest = {
   headers: {
@@ -35,10 +31,13 @@ export type MinimalMcpResponse = {
 export function createCalendarMcpServer(
   receipts: SelloReceipts = sello.service(),
 ) {
-  const createEvent = receipts.tool<MinimalMcpRequest, MinimalMcpResponse>(
-    "mcp.tools/call.calendar.create_event",
-    async (request) => {
-      const args = request.body.params.arguments;
+  const createEvent = receipts.mcpTool<
+    MinimalMcpRequest["body"]["params"]["arguments"],
+    MinimalMcpResponse,
+    MinimalMcpRequest
+  >(
+    "calendar.create_event",
+    async (args, request) => {
       const title = readString(args.title, "title");
 
       return {
@@ -54,13 +53,6 @@ export function createCalendarMcpServer(
         },
       };
     },
-    {
-      canonicalizeInput: (request) => canonicalJsonBytes({
-        method: request.body.method,
-        params: request.body.params,
-      }),
-      canonicalizeOutput: (response) => canonicalJsonBytes(response),
-    },
   );
 
   return {
@@ -79,7 +71,7 @@ export function createCalendarMcpServer(
         };
       }
 
-      return await createEvent(request);
+      return await createEvent(request.body.params.arguments, request);
     },
 
     flush: () => receipts.flush(),

package/sdks/typescript/examples/mcp-tool-server.ts

@@ -3,7 +3,6 @@
 import { pathToFileURL } from "node:url";
 
 import {
-  canonicalJsonBytes,
   sello,
   type SdkSubmissionLog,
   type SelloReceipts,
@@ -76,7 +75,10 @@ export type McpToolServerExampleOptions = {
 export function createSelloMcpToolServer(receipts: SelloReceipts): SelloMcpToolServer {
   const tools = new Map<
     string,
-    (request: McpHttpToolCall) => Promise<McpHttpToolResponse>
+    (
+      args: Record<string, unknown>,
+      request: McpHttpToolCall,
+    ) => Promise<McpHttpToolResponse>
   >();
 
   return {
@@ -88,23 +90,20 @@ export function createSelloMcpToolServer(receipts: SelloReceipts): SelloMcpToolS
         throw new TypeError(`MCP tool ${name} is already registered`);
       }
 
-      const wrapped = receipts.tool<McpHttpToolCall, McpHttpToolResponse>(
-        `mcp.tools/call.${name}`,
-        async (request) => ({
+      const wrapped = receipts.mcpTool<
+        Record<string, unknown>,
+        McpHttpToolResponse,
+        McpHttpToolCall
+      >(
+        name,
+        async (args, request) => ({
           status: 200,
           body: {
             jsonrpc: "2.0",
             id: request.body.id,
-            result: await handler(request.body.params.arguments),
+            result: await handler(args),
           },
         }),
-        {
-          canonicalizeInput: (request) => canonicalJsonBytes({
-            method: request.body.method,
-            params: request.body.params,
-          }),
-          canonicalizeOutput: (response) => canonicalJsonBytes(response.body),
-        },
       );
 
       tools.set(name, wrapped);
@@ -120,7 +119,7 @@ export function createSelloMcpToolServer(receipts: SelloReceipts): SelloMcpToolS
         return jsonRpcError(request.body.id, -32601, "tool not found");
       }
 
-      return await tool(request);
+      return await tool(request.body.params.arguments, request);
     },
   };
 }

package/sdks/typescript/src/cli/sello.ts

@@ -200,6 +200,29 @@ async function devCommand(args: string[]): Promise<void> {
     console.log(`Local dev log: ${logPath}`);
     console.log(`Loaded ${devLogEntryCountLabel(loadedEntries)}.`);
   });
+  server.on("error", (error) => {
+    if (isPortInUse(error)) {
+      console.error(`sello: port ${port} is already in use.`);
+      console.error("");
+      console.error("Try:");
+      console.error(`  sello dev --port ${port + 1}`);
+      console.error("");
+      console.error("Or stop the process using that port:");
+      console.error(`  lsof -nP -iTCP:${port} -sTCP:LISTEN`);
+      process.exitCode = 1;
+      return;
+    }
+
+    if (isListenError(error)) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`sello: could not start dev server on port ${port}.`);
+      console.error(message);
+      process.exitCode = 1;
+      return;
+    }
+
+    throw error;
+  });
 }
 
 async function emitDemoCommand(args: string[]): Promise<void> {
@@ -258,14 +281,7 @@ async function callHttpDemoCommand(args: string[]): Promise<void> {
   );
   const url = readFlag(args, "--url") ?? "http://localhost:8790/calendar/events";
   const title = readFlag(args, "--title") ?? "Ship Sello";
-  const response = await fetch(url, {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${state.agentToken}`,
-      "content-type": "application/json",
-    },
-    body: JSON.stringify({ title }),
-  });
+  const response = await fetchHttpDemo(url, state.agentToken, title);
   const responseText = await response.text();
 
   if (!response.ok) {
@@ -284,6 +300,31 @@ async function callHttpDemoCommand(args: string[]): Promise<void> {
   console.log(`  ${actionViewerUrl(state)}`);
 }
 
+async function fetchHttpDemo(
+  url: string,
+  agentToken: string,
+  title: string,
+): Promise<Response> {
+  try {
+    return await fetch(url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${agentToken}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ title }),
+    });
+  } catch (error) {
+    if (isFetchFailed(error)) {
+      throw new TypeError(
+        `could not reach the HTTP demo route at ${url}.\n\nStart it in another terminal:\n  node sello-http-route.mjs`,
+      );
+    }
+
+    throw error;
+  }
+}
+
 function initDemoCommand(args: string[]): void {
   const output = readFlag(args, "--output") ?? "emit-receipt.mjs";
   const force = args.includes("--force");
@@ -788,6 +829,22 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function isPortInUse(error: unknown): boolean {
+  return (
+    isRecord(error) &&
+    error.code === "EADDRINUSE" &&
+    error.syscall === "listen"
+  );
+}
+
+function isListenError(error: unknown): boolean {
+  return isRecord(error) && error.syscall === "listen";
+}
+
+function isFetchFailed(error: unknown): boolean {
+  return error instanceof TypeError && error.message === "fetch failed";
+}
+
 function printHelp(): void {
   console.log(`Usage:
   sello dev [--port 8787] [--service service-id] [--dry-run]

package/sdks/typescript/src/sdk/service.ts

@@ -42,6 +42,36 @@ export type SelloToolOptions<Request, Response> = {
   deniedResponse?: (request: Request) => Response | Promise<Response>;
 };
 
+export type SelloMcpToolInvocation<Args, Context = unknown> = {
+  name: string;
+  arguments: Args;
+  context: Context;
+};
+
+export type SelloMcpToolHandler<Args, Response, Context = unknown> = (
+  args: Args,
+  context: Context,
+) => Response | Promise<Response>;
+
+export type SelloMcpToolOptions<Args, Response, Context = unknown> = {
+  actionType?: string;
+  authorizationToken?: SelloValueOrGetter<
+    SelloMcpToolInvocation<Args, Context>,
+    string | Uint8Array
+  >;
+  canonicalizeInput?: (
+    invocation: SelloMcpToolInvocation<Args, Context>,
+  ) => Uint8Array;
+  canonicalizeOutput?: (response: Response) => Uint8Array;
+  canonicalizeError?: (error: unknown) => Uint8Array;
+  isDenied?: (
+    invocation: SelloMcpToolInvocation<Args, Context>,
+  ) => boolean | Promise<boolean>;
+  deniedResponse?: (
+    invocation: SelloMcpToolInvocation<Args, Context>,
+  ) => Response | Promise<Response>;
+};
+
 export type SelloServiceConfig = {
   service?: string;
   serviceKey?: ServiceKeyInput;
@@ -66,6 +96,11 @@ export type SelloReceipts = {
     handler: SelloToolHandler<Request, Response>,
     options?: SelloToolOptions<Request, Response>,
   ): SelloToolHandler<Request, Response>;
+  mcpTool<Args, Response, Context = unknown>(
+    name: string,
+    handler: SelloMcpToolHandler<Args, Response, Context>,
+    options?: SelloMcpToolOptions<Args, Response, Context>,
+  ): SelloMcpToolHandler<Args, Response, Context>;
   flush(): Promise<void>;
 };
 
@@ -115,90 +150,126 @@ export function createSelloService(input?: SelloServiceInput): SelloReceipts {
     return publisher;
   }
 
-  return {
-    tool<Request, Response>(
-      actionType: string,
-      handler: SelloToolHandler<Request, Response>,
-      options: SelloToolOptions<Request, Response> = {},
-    ): SelloToolHandler<Request, Response> {
-      if (typeof actionType !== "string" || actionType.length === 0) {
-        throw new TypeError("Sello action type must be a non-empty string");
-      }
+  function wrapTool<Request, Response>(
+    actionType: string,
+    handler: SelloToolHandler<Request, Response>,
+    options: SelloToolOptions<Request, Response> = {},
+  ): SelloToolHandler<Request, Response> {
+    if (typeof actionType !== "string" || actionType.length === 0) {
+      throw new TypeError("Sello action type must be a non-empty string");
+    }
 
-      return async (request: Request): Promise<Response> => {
-        const resolved = await config();
-        const authorizationToken = resolveValue(
-          options.authorizationToken ?? defaultAuthorizationToken,
-          request,
-        );
-        const tokenIssuerPublicKey = await resolveTokenIssuerPublicKey(resolved.tokenIssuer);
-        const verifiedToken = verifySelloJwsToken({
-          authorizationToken,
-          issuerPublicKey: tokenIssuerPublicKey,
+    return async (request: Request): Promise<Response> => {
+      const resolved = await config();
+      const authorizationToken = resolveValue(
+        options.authorizationToken ?? defaultAuthorizationToken,
+        request,
+      );
+      const tokenIssuerPublicKey = await resolveTokenIssuerPublicKey(resolved.tokenIssuer);
+      const verifiedToken = verifySelloJwsToken({
+        authorizationToken,
+        issuerPublicKey: tokenIssuerPublicKey,
+      });
+      const selloLogs = selectSelloLogs(
+        verifiedToken.selloLogs,
+        resolved.fallbackSelloLogs,
+        resolved.log.logUrl,
+      );
+      const base = {
+        authorizationTokenBytes: verifiedToken.authorizationTokenBytes,
+        ownerHpkePublicKey: verifiedToken.ownerHpkePublicKey,
+        selloLogs,
+        serviceKid: resolved.serviceKid,
+        servicePrivateKey: resolved.servicePrivateKey,
+        serviceIdentifier: resolved.service,
+        logUrl: resolved.log.logUrl,
+        actionType,
+        actionInputBytes: (options.canonicalizeInput ?? canonicalJsonBytes)(request),
+        timestamp: resolved.now(),
+      };
+
+      if (options.isDenied && (await options.isDenied(request))) {
+        const response = options.deniedResponse
+          ? await options.deniedResponse(request)
+          : undefined;
+        const receipt = emitReceipt({
+          ...base,
+          actionOutputBytes: new Uint8Array(),
+          resultStatus: "denied",
         });
-        const selloLogs = selectSelloLogs(
-          verifiedToken.selloLogs,
-          resolved.fallbackSelloLogs,
-          resolved.log.logUrl,
-        );
-        const base = {
-          authorizationTokenBytes: verifiedToken.authorizationTokenBytes,
-          ownerHpkePublicKey: verifiedToken.ownerHpkePublicKey,
-          selloLogs,
-          serviceKid: resolved.serviceKid,
-          servicePrivateKey: resolved.servicePrivateKey,
-          serviceIdentifier: resolved.service,
-          logUrl: resolved.log.logUrl,
-          actionType,
-          actionInputBytes: (options.canonicalizeInput ?? canonicalJsonBytes)(request),
-          timestamp: resolved.now(),
-        };
-
-        if (options.isDenied && (await options.isDenied(request))) {
-          const response = options.deniedResponse
-            ? await options.deniedResponse(request)
-            : undefined;
-          const receipt = emitReceipt({
-            ...base,
-            actionOutputBytes: new Uint8Array(),
-            resultStatus: "denied",
-          });
-          resolved.onReceipt?.({ resultStatus: "denied", receipt, response });
-          await submit(resolved, receipt, base.timestamp);
-
-          if (options.deniedResponse) {
-            return response as Response;
-          }
-
-          throw new SelloDeniedError(receipt);
-        }
+        resolved.onReceipt?.({ resultStatus: "denied", receipt, response });
+        await submit(resolved, receipt, base.timestamp);
 
-        let response: Response;
-        try {
-          response = await handler(request);
-        } catch (error) {
-          const receipt = emitReceipt({
-            ...base,
-            actionOutputBytes: (options.canonicalizeError ?? canonicalErrorBytes)(
-              error,
-            ),
-            resultStatus: "error",
-          });
-          resolved.onReceipt?.({ resultStatus: "error", receipt, error });
-          await submit(resolved, receipt, base.timestamp);
-          throw error;
+        if (options.deniedResponse) {
+          return response as Response;
         }
 
+        throw new SelloDeniedError(receipt);
+      }
+
+      let response: Response;
+      try {
+        response = await handler(request);
+      } catch (error) {
         const receipt = emitReceipt({
           ...base,
-          actionOutputBytes: (options.canonicalizeOutput ?? canonicalJsonBytes)(
-            response,
+          actionOutputBytes: (options.canonicalizeError ?? canonicalErrorBytes)(
+            error,
           ),
-          resultStatus: "success",
+          resultStatus: "error",
         });
-        resolved.onReceipt?.({ resultStatus: "success", receipt, response });
+        resolved.onReceipt?.({ resultStatus: "error", receipt, error });
         await submit(resolved, receipt, base.timestamp);
-        return response;
+        throw error;
+      }
+
+      const receipt = emitReceipt({
+        ...base,
+        actionOutputBytes: (options.canonicalizeOutput ?? canonicalJsonBytes)(
+          response,
+        ),
+        resultStatus: "success",
+      });
+      resolved.onReceipt?.({ resultStatus: "success", receipt, response });
+      await submit(resolved, receipt, base.timestamp);
+      return response;
+    };
+  }
+
+  return {
+    tool<Request, Response>(
+      actionType: string,
+      handler: SelloToolHandler<Request, Response>,
+      options: SelloToolOptions<Request, Response> = {},
+    ): SelloToolHandler<Request, Response> {
+      return wrapTool(actionType, handler, options);
+    },
+    mcpTool<Args, Response, Context = unknown>(
+      name: string,
+      handler: SelloMcpToolHandler<Args, Response, Context>,
+      options: SelloMcpToolOptions<Args, Response, Context> = {},
+    ): SelloMcpToolHandler<Args, Response, Context> {
+      if (typeof name !== "string" || name.length === 0) {
+        throw new TypeError("MCP tool name must be a non-empty string");
+      }
+
+      const wrapped = wrapTool<SelloMcpToolInvocation<Args, Context>, Response>(
+        options.actionType ?? `mcp.tools/call.${name}`,
+        async (invocation) => handler(invocation.arguments, invocation.context),
+        {
+          authorizationToken:
+            options.authorizationToken ?? defaultMcpAuthorizationToken,
+          canonicalizeInput:
+            options.canonicalizeInput ?? defaultMcpCanonicalizeInput,
+          canonicalizeOutput: options.canonicalizeOutput,
+          canonicalizeError: options.canonicalizeError,
+          isDenied: options.isDenied,
+          deniedResponse: options.deniedResponse,
+        },
+      );
+
+      return async (args: Args, context: Context): Promise<Response> => {
+        return await wrapped({ name, arguments: args, context });
       };
     },
     async flush(): Promise<void> {
@@ -482,23 +553,113 @@ function selectSelloLogs(
 }
 
 function defaultAuthorizationToken(request: unknown): string | Uint8Array {
+  const token = authorizationTokenFromUnknown(request);
+  if (token) {
+    return token;
+  }
+
+  throw new TypeError(
+    "Sello authorization token not found. Pass authorizationToken or include request.authorizationToken.",
+  );
+}
+
+function defaultMcpAuthorizationToken(
+  invocation: SelloMcpToolInvocation<unknown, unknown>,
+): string | Uint8Array {
+  const fromContext = authorizationTokenFromUnknown(invocation.context);
+  if (fromContext) {
+    return fromContext;
+  }
+
+  throw new TypeError(
+    "Sello MCP authorization token not found. Pass authorizationToken or include an Authorization header in the MCP context.",
+  );
+}
+
+function defaultMcpCanonicalizeInput(
+  invocation: SelloMcpToolInvocation<unknown, unknown>,
+): Uint8Array {
+  return canonicalJsonBytes({
+    method: "tools/call",
+    params: {
+      name: invocation.name,
+      arguments: invocation.arguments,
+    },
+  });
+}
+
+function authorizationTokenFromUnknown(value: unknown): string | Uint8Array | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const direct = value.authorizationToken ?? value.authorization;
+  if (typeof direct === "string" || direct instanceof Uint8Array) {
+    return stripBearer(direct);
+  }
+
+  const headers = value.headers;
+  const fromHeaders = authorizationTokenFromHeaders(headers);
+  if (fromHeaders) {
+    return fromHeaders;
+  }
+
+  const requestInfo = value.requestInfo;
+  if (isRecord(requestInfo)) {
+    const fromRequestInfo = authorizationTokenFromHeaders(requestInfo.headers);
+    if (fromRequestInfo) {
+      return fromRequestInfo;
+    }
+  }
+
+  const request = value.request;
   if (isRecord(request)) {
-    const direct = request.authorizationToken ?? request.authorization;
-    if (typeof direct === "string" || direct instanceof Uint8Array) {
-      return stripBearer(direct);
+    const fromRequest = authorizationTokenFromHeaders(request.headers);
+    if (fromRequest) {
+      return fromRequest;
     }
+  }
 
-    const headers = request.headers;
-    if (isRecord(headers)) {
-      const header = headers.authorization ?? headers.Authorization;
-      if (typeof header === "string") {
-        return stripBearer(header);
-      }
+  const authInfo = value.authInfo;
+  if (isRecord(authInfo)) {
+    const token = authInfo.token ?? authInfo.accessToken ?? authInfo.access_token;
+    if (typeof token === "string" || token instanceof Uint8Array) {
+      return stripBearer(token);
     }
   }
 
-  throw new TypeError(
-    "Sello authorization token not found. Pass authorizationToken or include request.authorizationToken.",
+  return undefined;
+}
+
+function authorizationTokenFromHeaders(
+  headers: unknown,
+): string | Uint8Array | undefined {
+  if (isHeadersLike(headers)) {
+    const header = headers.get("authorization") ?? headers.get("Authorization");
+    if (typeof header === "string") {
+      return stripBearer(header);
+    }
+  }
+
+  if (!isRecord(headers)) {
+    return undefined;
+  }
+
+  const header = headers.authorization ?? headers.Authorization;
+  if (typeof header === "string" || header instanceof Uint8Array) {
+    return stripBearer(header);
+  }
+
+  return undefined;
+}
+
+function isHeadersLike(
+  value: unknown,
+): value is { get(name: string): string | null } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { get?: unknown }).get === "function"
   );
 }