# MCP Server

Abbotik exposes its canonical MCP server at `/mcp` using modern Streamable HTTP semantics.

For older clients that still require the deprecated HTTP+SSE transport, Abbotik also exposes legacy compatibility routes at `/sse` and `/messages`.

## Canonical MCP Endpoint

`/mcp`

### Methods

- **POST /mcp** — send JSON-RPC initialize, ping, tools/list, tools/call, notifications, and responses
- **GET /mcp** — optional SSE stream for server-to-client messages
- **DELETE /mcp** — terminate a stateful MCP session

## Transport Model

Abbotik now treats `/mcp` as a Streamable HTTP MCP endpoint:

- clients send JSON-RPC over `POST /mcp`
- the server may respond with either JSON or SSE
- clients may open `GET /mcp` with `Accept: text/event-stream`
- sessions are established by the server and returned in `Mcp-Session-Id`
- subsequent requests should include both `Mcp-Session-Id` and `MCP-Protocol-Version`

Supported protocol versions currently include:

- `2025-03-26`
- `2025-06-18`
- `2025-11-25`

If no protocol version is otherwise available, Abbotik defaults to `2025-03-26`.

## Session Model

1. Start with `POST /mcp` and JSON-RPC `initialize`.
2. Persist the returned `Mcp-Session-Id` response header.
3. Send that header on later `POST /mcp`, `GET /mcp`, and `DELETE /mcp` requests.
4. Send `MCP-Protocol-Version` on requests after initialize.
5. When finished, send `DELETE /mcp` with the same `Mcp-Session-Id` header.

Abbotik keeps auth and machine-auth state scoped to the MCP session, so tool calls using the same session share the same stored token state.

## Tools

| Tool | Purpose |
|------|---------|
| `abbot_auth` | Register tenants, log in, provision machine auth, inspect or update stored token state, and dissolve tenants. |
| `abbot_describe` | Inspect and mutate model schemas and field definitions. |
| `abbot_find` | Run structured find queries and saved filters. |
| `abbot_data` | Read and mutate model records with operation-oriented semantics. |
| `abbot_related` | Traverse and mutate owned relationships. |
| `abbot_bulk` | Execute transactional bulk operation payloads. |

## Tool Navigation

- `abbot_auth` actions: `tenants`, `login`, `register`, `refresh`, `dissolve_request`, `dissolve_confirm`, `provision`, `challenge`, `verify`, `machine_connect`, `token_get`, `token_set`, `token_clear`
- `abbot_describe` operations: `list`, `get`, `create`, `update`, `delete`, `fields_list`, `fields_get`, `fields_create`, `fields_bulk_create`, `fields_update`, `fields_bulk_update`, `fields_delete`
- `abbot_find` operations: `query`, `run-filter`
- `abbot_data` operations: `select-all`, `select-one`, `select-404`, `create-one`, `create-all`, `upsert-one`, `upsert-all`, `update-one`, `update-any`, `update-all`, `delete-one`, `delete-any`, `delete-all`
- `abbot_related` operations: `select-all`, `create-one`, `update-all`, `delete-all`, `select-child-all`, `update-child-all`, `delete-child-all`
- `abbot_bulk` accepts the same `operations` array shape as `POST /api/bulk`

## Quick Start: Streamable HTTP

```bash
# 1. Initialize a session and capture the session header
curl -i -X POST http://localhost:9001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26"
    }
  }'

# 2. List tools using the returned session and protocol headers
curl -X POST http://localhost:9001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: <session-id>" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'
```

## Legacy HTTP+SSE Compatibility

For older MCP clients, Abbotik also exposes:

- **GET /sse** — opens the legacy SSE stream and emits an `endpoint` event
- **POST /messages** — accepts subsequent JSON-RPC messages using the session id returned by the `endpoint` event

This compatibility surface exists for older clients only. New clients should use `/mcp`.

## Endpoint Summary

| Method | Path | Description |
|--------|------|-------------|
| GET | [`/mcp`](GET.md) | Open an MCP SSE stream when the client requests `text/event-stream`. |
| POST | [`/mcp`](POST.md) | Accept Streamable HTTP JSON-RPC requests and return JSON or SSE responses. |
| DELETE | [`/mcp`](DELETE.md) | Terminate the supplied stateful MCP session. |
| GET | `/sse` | Open the deprecated legacy SSE transport and emit an `endpoint` event. |
| POST | `/messages` | Accept deprecated legacy SSE follow-up messages. |

## Related Documentation

- [API overview](/docs)
- [Root agent entrypoint](/llms.txt)
- [Auth API](/docs/auth)
- [API Keys](/docs/api/keys)