Integrate an MCP host - Praxa

Inspect the published contracts

import {
  MCP_PROTOCOL_VERSION,
  MCP_SERVER_NAME,
  MCP_SERVER_VERSION,
  PRAXA_MCP_TOOLS,
} from "@praxa/mcp-contracts";

console.log({
  protocol: MCP_PROTOCOL_VERSION,
  server: MCP_SERVER_NAME,
  serverVersion: MCP_SERVER_VERSION,
  tools: PRAXA_MCP_TOOLS.map((tool) => ({
    name: tool.name,
    scope: tool.requiredScope,
    annotations: tool.annotations,
  })),
});

Register with your host

Host SDKs use different registration APIs and JSON Schema adapters. The following is intentionally framework-neutral:

for (const tool of PRAXA_MCP_TOOLS) {
  host.register({
    name: tool.name,
    description: tool.description,
    inputSchema: adaptDraft202012SchemaForHost(tool.inputSchema),
    annotations: tool.annotations,
    execute: async (input) =>
      callGatewayRoute(tool.method, tool.path, input, delegatedToken),
  });
}

Do not rename the aura_* tool identifiers. They are stable wire values even when the host displays Praxa branding.

Preserve the executor boundary

The registration callback should be the only layer that translates an MCP tool call into a Gateway request. It must:

validate the tool input against the published schema;
interpolate only the declared pathArgument;
remove the path field from the JSON body when the route expects it in the URL;
attach a short-lived delegated token with the exact requiredScope;
preserve one idempotency key for an exact mutation replay;
map bounded Gateway problems to isError: true tool results;
return a redacted structured result that the host can verify.

Never accept tenant, token, provider credential, or route override values from model-generated input.

Test the adapter itself

Use a fake executor to assert all 12 registrations, exact names, annotations, schema identity, path interpolation, body projection, idempotency handling, and error mapping. Then run one read-only authenticated canary against the intended deployment. See host-specific setup and MCP troubleshooting.

Last modified on August 14, 2026