# MCP Server

Omnia Exchange provides an MCP (Model Context Protocol) server for AI and LLM agent integration. The server implements the [Model Context Protocol](https://modelcontextprotocol.io/) over Streamable HTTP, enabling agents to discover and invoke exchange tools programmatically.

### Endpoint

- **Demo/UAT** - `https://api.demo.omniaexchange.com/api/mcp`
- **Production** - `https://api.production.omniaexchange.com/api/mcp`

`POST` — Send JSON-RPC requests (initialize, tools/list, tools/call, ping)

`DELETE` — Terminate a session

### Protocol Version

The server implements MCP protocol version `2025-11-25`.

### Transport

The server uses Streamable HTTP transport. SSE streaming is not supported — `GET /api/mcp` returns `405`.

### Authentication

The server implements [OAuth 2.0 Client Credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) for authentication, following the MCP authorization specification.

**Discovery endpoints:**

- `GET /.well-known/oauth-protected-resource` — returns the resource metadata (scopes, authorization servers)
- `GET /.well-known/oauth-authorization-server` — returns the authorization server metadata (token endpoint, supported grants)

**Obtaining a token:**

`POST /oauth/token` with form parameters:
- `grant_type` = `client_credentials`
- `client_id` = your API key ID
- `client_secret` = your API key secret

The response includes an `access_token`, `token_type`, `expires_in`, and granted `scope`.

**Usage:** Include the token as `Authorization: Bearer ` on `tools/call` requests. Session management methods (`initialize`, `tools/list`, `ping`) do not require authentication.

### Session Lifecycle

Clients must initialize a session before calling tools. The server returns a session ID in the `MCP-Session-Id` response header on successful initialization. This session ID must be included as a request header on all subsequent requests. Sessions expire after a period of inactivity — clients should re-initialize if they receive an "Invalid or missing session" error.

### Tool Discovery

Available tools are discoverable via the `tools/list` method. Each tool definition includes a name, description, and input schema. Tools currently span market data, account data, and order history categories.

### Important Notes

- SSE streaming (`GET /api/mcp`) is not supported. All communication uses request/response over `POST`.
- Authentication (Bearer token) is only required for `tools/call`. Other methods (`initialize`, `tools/list`, `ping`) work without a token.

## MCP JSON-RPC

`POST /mcp`

Send JSON-RPC requests to the MCP server (initialize, tools/list, tools/call, ping). See the MCP Server section description for full protocol details including authentication, session lifecycle, and tool discovery.

**Responses**

- **200**: JSON-RPC response

**Example**

```bash
curl -X POST "https://api.demo.omniaexchange.com/api/mcp"
```

---

## Terminate MCP Session

`DELETE /mcp`

Terminate an active MCP session. The session ID must be included in the `MCP-Session-Id` request header.

**Responses**

- **200**: Session terminated

**Example**

```bash
curl -X DELETE "https://api.demo.omniaexchange.com/api/mcp"
```

---