# MCP

The same api, the same key, spoken as MCP tools. Endpoint:

```text
POST https://api.mivia.app/mcp
```

Stateless streamable-http JSON-RPC: no session id, no SSE stream. An
MCP call is a call that arrived through a different envelope; it
bills the key's tenant exactly like a REST call.

## Client config

Claude, Cursor, and any client that takes static headers:

```json
{
  "mcpServers": {
    "mivia": {
      "url": "https://api.mivia.app/mcp",
      "headers": { "Authorization": "Bearer mivia_..." }
    }
  }
}
```

## Protocol methods

- `initialize` - version handshake and server card
- `tools/list` - the tool table below, with full input schemas
- `tools/call` - one billed call
- `ping` - answers an empty result

Smoke test from a shell:

```bash
curl -X POST https://api.mivia.app/mcp \
  -H 'Authorization: Bearer mivia_...' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Tools

| tool | what it does | required fields | optional fields |
| --- | --- | --- | --- |
| `mivia_small_json_extract` | Extract a structured JSON record from one free-text input: a ticket, a log line, a message. | `text` | `dump` |
| `mivia_small_json_structure` | Structure a multi-line dump into grouped JSON sections: stack traces grouped, diffs kept atomic. | `text`, `schema` | none |
| `mivia_small_json_select` | Rank the candidates given in the input text, zero-shot. | `text`, `candidates` | none |
| `mivia_small_json_grade` | Grade the input's severity on a fixed four-tier scale. | `text` | `anchors` |
| `mivia_small_json_guard` | Judge a proposed tool call; returns CALL, CLARIFY, or ABSTAIN. | `request` | `tools` |

Every tool forwards its fields to the model verbatim, so the field tables under [REST api](/docs/rest-api) describe each field in full.


## Refusals

A business refusal never breaks the protocol. A refused call answers
HTTP 200 with `isError: true` inside the result and one of `rate
limited`, `balance empty; top up at /billing`, or `model unavailable`
as the text. The retry and top-up rules live on the
[errors](/docs/errors) page.