Use Lucid with MCP

Lucid does not currently ship an MCP server adapter, MCP client adapter, MCP tool generator, or a native payment transport for MCP. The supported seam today is a server-side MCP tool whose implementation calls a canonical Lucid HTTP endpoint with a policy-controlled paid Fetch client.

That distinction matters: an HTTP tool wrapper can compose the products safely, but it does not make the Lucid service MCP-native and does not let an arbitrary MCP client complete x402 or Payment-Auth negotiation by itself.

Current support boundary

Do not label a service “paid MCP” merely because an MCP tool happens to make a paid HTTP request internally.

Safe current architecture

MCP host / agent framework
  → application-owned MCP server
    → tool argument schema + approval
      → budgeted paid Fetch client
        → canonical Lucid HTTPS endpoint
          → payment + policy + idempotency + handler
        ← output + settlement evidence
    ← redacted MCP tool result

The MCP server is the buyer. Its server-side wallet and policy decide whether the tool may spend. The remote MCP host never receives the wallet key or x402 credential.

async function executePaidResearchTool(args: unknown, requestId: string) {
  const input = researchInput.parse(args);
  const operationId = `mcp:research:${requestId}`;

  const output = await buyResearch(input, { operationId });

  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify(output),
      },
    ],
  };
}

Register that function with the current SDK for your MCP server. The MCP SDK's registration syntax is intentionally not reproduced here because Lucid does not own or version it; the paid-client contract is the integration seam.

buyResearch() should be the independently tested client from Compose with agent frameworks, built on the controls in Build a budgeted buyer.

Why the tool must call the HTTP route

Do not import the seller's handler and invoke it directly from an MCP server if the tool is meant to preserve Lucid's paid service contract. A direct function call bypasses:

• payment challenge and credential verification;
• recipient and incoming policy admission;
• target-side HTTP idempotency;
• canonical request/output validation and response evidence;
• adapter-independent observability and settlement finalization.

If the MCP server and Lucid seller share one process, loopback HTTP is still the currently documented public seam. A future native adapter should enter the same authorization transaction directly through a supported runtime API rather than duplicating it.

Identity, trust, and approvals

MCP tool discovery says which tool exists; it does not authorize wallet spend. Treat descriptions and schemas as untrusted input when they arrive from a remote server.

• Allowlist the MCP server and Lucid service separately.
• Validate the final HTTPS URL after redirects and DNS resolution.
• Bind policy to the expected payee, network, asset, amount, and tool name.
• Require human approval before the first payment to a new recipient or above the autonomous tier.
• Scope one buyer wallet and durable budget to the tenant/principal invoking the tool.
• Never return a payment credential, SIWX signature, wallet key, facilitator token, or raw authorization context in MCP content.

For remote MCP servers, follow the host/runtime's authentication and tool approval controls. For local stdio servers, remember that local process access and inherited environment variables become part of the trust boundary.

Retry and cancellation

Map the MCP request/tool-call ID to a stable business operation ID. Preserve it when the host retries or resumes the tool call.

Observability contract

Correlate, but do not conflate:

MCP session ID → MCP request ID → tool call ID → business operation ID
               → Lucid run/task ID → payment receipt/transaction ID

Log the tool name, sanitized target, policy decision, amount/network/payee, Lucid status/code, and receipt reference. Do not log full MCP prompts or tool arguments by default; they may contain tenant data.

What native support would require

A future Lucid MCP profile should not be described as supported until it has:

1. an explicit MCP protocol and SDK version;
2. deterministic projection of entrypoint schemas into tool definitions;
3. a specified x402 or Payment-Auth challenge, credential, and receipt mapping;
4. request/body/tool binding and replay rules;
5. cancellation, progress, streaming, and task semantics;
6. stdio versus network transport threat models;
7. official-client interoperability and negative conformance tests;
8. the same policy, idempotency, settlement, and recording transaction as HTTP.

The formal Payment Authentication work includes a separate JSON-RPC/MCP transport Internet-Draft. It is not implemented by Lucid's current mppx integration. x402 ecosystems also publish provider-specific MCP bridges, such as the CDP x402 MCP guide and Vercel 402-mcp announcement; those do not automatically establish compatibility with Lucid.

Continue with MCP/framework security and payment recovery.