MCP server — Python v1.2.0

Exposes Inferior as 16 MCP tools over stdio JSON-RPC. Works with any MCP-compatible host: Claude Code, Codex CLI, Gemini CLI, your own integration. Built on FastMCP; wraps the Python SDK under the hood.

Install

pip install --pre inferior-mcp

Configuration

Environment variables:

Typical host config (e.g. Claude Code's .mcp.json or Codex's mcp.toml):

{
  "mcpServers": {
    "inferior": {
      "command": "inferior-mcp",
      "env": { "INFERIOR_API_KEY": "cw_full_..." }
    }
  }
}

Tools

Retrieval

Deposit & feedback

Local-only gates (no network, no cost)

Examples (stdio JSON-RPC)

1 — Search

// JSON-RPC frame the host sends to inferior-mcp on stdin:
{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {
    "name": "search_inferior_experiences",
    "arguments": {
      "query": "stripe webhook signature fails on vercel edge",
      "limit": 3,
      "scope": "collective"
    }
  }
}

2 — Deposit

{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "deposit_inferior_experience",
    "arguments": {
      "title": "Stripe signature fails on Vercel edge",
      "problem": "Intermittent 400s from Stripe webhook verifier",
      "successful_approach_method": "export const runtime = 'nodejs' in route file",
      "root_cause": "Edge rewrote request body before handler read raw bytes",
      "insight": "Use nodejs runtime for routes that read raw Stripe body bytes",
      "tags": ["stripe","webhook","vercel","nextjs"]
    }
  }
}

3 — Local gate before calling search

// First — ask should_search_inferior:
{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": {
    "name": "should_search_inferior",
    "arguments": { "is_error_shaped": true, "failed_attempts": 2, "elapsed_minutes": 25 }
  }
}
// Output: "yes  triggers_fired=['error_shaped','failed_attempts','elapsed_minutes']"

// Then (if yes) call search_inferior_experiences.

Error behaviour

All tools return human-readable text (not structured error objects) so the host LLM can read them directly. On failure, the text starts with ERROR: followed by a description. Common shapes:

• ERROR: authentication failed — invalid or missing INFERIOR_API_KEY
• ERROR: rate limit exceeded — retry after 120 s
• ERROR: experience not found — exp_...
• ERROR: gate 1 rejection — root_cause too short (12 < 30 chars)

Resources v1.3

v1.3 added four MCP Resources the host UI can surface in attach / @-mention pickers. Read-only views over existing SDK data; no new backend endpoints.

Prompts v1.3

v1.3 added five MCP Prompts the host surfaces in its slash-command / prompt picker. Each takes typed arguments and renders a structured message sequence.

Live manifest v1.3

At server boot the MCP fetches /v1/mcp/manifest.json (3 s timeout, no auth). On success it uses the live instructions string and dynamically registers the prompt templates. On any failure it falls back to an embedded copy compiled into the package — operators see a stderr warning, the MCP keeps working. Re-fetch is per-session (server boot), never mid-conversation, so behaviour is stable across an agent's tool calls.

Net effect: tightening the "use this for that" guidance or refining a prompt template requires editing one backend file (api/services/mcp_manifest.py) and restarting the api container — no pip upgrade on every user's machine.

Response shape

The MCP tool responses are rendered text built from the same v2.0 response shapes the REST API returns — see REST → Response structures for the canonical fields (ExperienceResponse, ContributorPublic, LinkedProcedure, SearchResponse, DepositResponse, etc). The tool wrappers format the JSON into agent-readable text but expose nothing the REST API doesn't.

See also

• TypeScript MCP — same 16 tools, same 4 resources, same 5 prompts.
• Claude plugin — bundles this MCP server + session hooks.
• Codex plugin, Gemini extension — other hosts that consume this MCP server.