# `MingaClaudeBridge.MCP`
[🔗](https://github.com/jsmestad/minga-claude-bridge/blob/main/lib/minga_claude_bridge/mcp.ex#L1)

Routes the JSON-RPC messages of the in-process MCP server named `"minga"`.

Claude Code hosts the bridge's tools as an SDK MCP server. It sends each JSON-RPC message to the bridge inside an `mcp_message` control request (see `MingaClaudeBridge.Wire.ControlRequest`) and waits for a `control_response`. `route/2` decides what to do with one message, given the tool declarations of the current turn. It is pure: it performs no I/O and holds no state.

## Outcomes

  * `{:reply, jsonrpc_id, result}` - answer with a JSON-RPC result. Used for `initialize`, `ping`, and `tools/list`.
  * `:acknowledge` - the message is not a request (a notification such as `notifications/initialized`, or a JSON-RPC response). Claude Code still waits for the control response, so the session answers with the acknowledgement the Agent SDK sends: `{"jsonrpc": "2.0", "result": {}, "id": 0}`.
  * `{:tool_call, call}` - a valid `tools/call`. Minga runs the tool, so the session does not answer yet. It holds the control request in `MingaClaudeBridge.ToolCalls` until the next Minga request carries the result.
  * `{:reply_error, jsonrpc_id, code, message}` - answer with a JSON-RPC error. `jsonrpc_id` is `nil` when the request id is not a string or integer.

`reply_line/2` encodes every outcome except `{:tool_call, _}` as the `control_response` line to write.

## Error codes

Standard JSON-RPC 2.0 codes:

  * `-32600` (invalid request) - the message has an `id` and a `method`, but one of them has the wrong JSON type.
  * `-32601` (method not found) - any method other than `initialize`, `ping`, `tools/list`, and `tools/call`.
  * `-32602` (invalid params) - a `tools/call` for a tool not offered this turn, without `params._meta["claudecode/toolUseId"]`, or with arguments that fail the minimal schema check. The MCP specification uses this code for unknown tools.

## Classifying messages

A message is a request when it has a `method` key and a non-null `id` key, which is the test the Agent SDK applies. Everything else is acknowledged.

## tools/list

The list is built from the declarations passed to `route/2`, so it always matches the current turn and is never cached. Each schema goes through `MingaClaudeBridge.MCP.Schema.flatten/1`, and the constraint that flattening removes is prepended to the description.

## Argument check (limited)

`tools/call` arguments must be a JSON object (an absent `arguments` counts as an empty object) and must contain every key in the flattened schema's top-level `required` list. Nothing else is checked: not property types, nested schemas, enums, formats, or the `anyOf`/`oneOf` constraints that flattening drops. The bridge does not include a JSON Schema validator. Minga validates the arguments against the full schema before it runs the tool, and reports a failure to the model as a tool error.

## Protocol version

`initialize` answers with the client's requested `protocolVersion` when it is one the Agent SDK 0.3.330 supports, and otherwise with the latest one, `"2025-11-25"`. This matches the MCP TypeScript SDK server.

Error messages name tools and argument keys but never contain argument values.

# `message`

```elixir
@type message() :: %{optional(String.t()) =&gt; term()}
```

A decoded JSON-RPC 2.0 message from an `mcp_message` control request.

# `outcome`

```elixir
@type outcome() :: reply() | {:tool_call, MingaClaudeBridge.MCP.CallRequest.t()}
```

# `reply`

```elixir
@type reply() ::
  {:reply, MingaClaudeBridge.Wire.jsonrpc_id(), map()}
  | :acknowledge
  | {:reply_error, MingaClaudeBridge.Wire.error_id(), integer(), String.t()}
```

# `tool`

```elixir
@type tool() :: %{name: String.t(), description: String.t(), input_schema: map()}
```

A tool Minga offers for the current turn. `input_schema` is a string-keyed JSON Schema.

# `reply_line`

```elixir
@spec reply_line(String.t(), reply()) :: MingaClaudeBridge.Wire.line()
```

Encodes a reply outcome as the `control_response` line that answers control request `request_id`.

# `route`

```elixir
@spec route(message(), [tool()]) :: outcome()
```

Routes one JSON-RPC message, given the tools offered for the current turn.

# `server_name`

```elixir
@spec server_name() :: String.t()
```

Returns the MCP server name the bridge registers with Claude Code.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
