Integration guide¶

Crank exposes the same tool registry through several transports. Pick the one your runtime supports; the tools, parameters, and structured envelopes are identical across all of them.

One source of truth¶

Every tool is defined once as a @mcp.tool on the FastMCP server. The crank_mcp.schema_export module introspects that live registry and emits per-framework definitions, so no integration hand-maintains its own copy:

Target	Exporter	Artifact
OpenAI function calling	`to_openai`	`openai.json`
Gemini `functionDeclarations`	`to_gemini`	`gemini.json`
OpenAPI 3.1 document	`build_openapi_document`	`reference/openapi.json`
LangChain `StructuredTool`	`to_langchain`	`langchain.json`

Regenerate the JSON artifacts at any time:

source .venv/bin/activate
python scripts/export-tool-schemas.py            # writes build/tool-schemas/*.json

The Markdown tool reference is generated from the same snapshot by docs/gen_tool_reference.py. Never hand-edit generated output; change the tool docstring and regenerate.

Transport 1: streamable HTTP (recommended)¶

The hosted server speaks the MCP streamable-HTTP transport: a single endpoint that takes JSON-RPC over POST and streams the event channel over GET.

https://mcp.crank.ing/mcp

CORS is open by default, so browser-based agents (OpenAI Responses, web LangChain) can call it cross-origin.
The transport returns an mcp-session-id header; echo it back on subsequent requests to resume a session.
HSTS and standard hardening headers are set on every response.

This is the right choice for most agents, including remote MCP connectors.

Transport 2: stdio (self-host / local)¶

For a local or embedded agent, run the server as a subprocess and speak MCP over stdin/stdout:

python -m crank_mcp.server          # stdio (default)

Example MCP client config (Claude Desktop style):

{
  "mcpServers": {
    "crank": {
      "command": "python",
      "args": ["-m", "crank_mcp.server"]
    }
  }
}

To self-host the HTTP transport instead:

MCP_TRANSPORT=http MCP_PORT=8900 python -m crank_mcp.server

Transport 3: OpenAPI / REST¶

If your runtime cannot speak MCP, consume the OpenAPI 3.1 document. Each tool is a POST /tools/{tool_name} operation whose request body is the tool's parameter schema and whose response is the structured envelope.

Spec: reference/openapi.json
Load it into an OpenAPI client generator, Postman, or a GPT Action.

Per-framework wiring¶

Framework	How	Detailed doc
Claude (API / Agent SDK / Desktop)	Remote MCP connector or stdio	Code examples
OpenAI (function calling / GPT Actions)	Feed `openai.json`; dispatch tool calls	`docs/integrations/openai.md`
Gemini	Feed `gemini.json` `functionDeclarations`; dispatch	`docs/integrations/gemini.md`
LangChain / CrewAI	Native MCP tool loader, or `langchain.json`	Code examples
Crank SDKs (Python / TypeScript)	`crank-sdk`, `@crank/sdk`	`docs/integrations/sdk.md`
OpenClaw autonomous managers	Provisioning API	`docs/integrations/openclaw.md`

Environments¶

Network	Use
devnet	Default sandbox. Build and test here.
mainnet	Production. Switch only when your flow is proven.

The tool surface is identical across networks. Free read tools work without any payment setup on either network; value-bearing actions require the x402 flow described in Authentication & x402.