# Protocol reference

> The JSON-RPC methods, request and response formats, OAuth discovery and error codes of GetIntel's MCP server, for building your own client or debugging one.

Source: https://getintel.ai/docs/mcp/protocol/

GetIntel's MCP server speaks **JSON-RPC 2.0 over HTTP** at a single endpoint. Most people never need this page: MCP clients handle it for you. It's here for building your own client or debugging one.

| | |
| --- | --- |
| **Endpoint** | `POST https://app.getintel.ai/mcp` |
| **Protocol versions** | `2025-06-18` (newest), `2025-03-26`, `2024-11-05` |
| **Server** | `getintel` 1.1.0 |
| **Auth** | OAuth sign-in, or an `Authorization: Bearer <token>` header |
| **Content type** | `application/json` |

`GET` and `DELETE` on `/mcp` both return `405`: the server doesn't open an SSE stream.

## Methods

### initialize

Send the protocol version your client speaks. The server echoes it back if it supports it, otherwise replies with `2025-06-18`.

```json
{
  "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": { "protocolVersion": "2025-06-18" }
}
```

```json
{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "getintel", "title": "GetIntel", "version": "1.1.0" },
    "instructions": "GetIntel tracks your AI visibility across ChatGPT, Perplexity, Gemini and Google AI Overviews…"
  }
}
```

`capabilities.tools.listChanged` is `false`: the tool list for a connection doesn't change without a reconnect.

### notifications/initialized

Notifications get HTTP `202` with no body, not a JSON-RPC response.

### ping

A liveness check with an empty result. Useful for confirming a connection is still good.

```json
{ "jsonrpc": "2.0", "id": 2, "method": "ping" }
```

```json
{ "jsonrpc": "2.0", "id": 2, "result": {} }
```

### tools/list

Returns the tools the connection may use: all 30 with action access, the 27 read tools otherwise. Each tool has a `name`, `title`, `description`, `inputSchema` (JSON Schema) and `annotations`.

```json
{ "jsonrpc": "2.0", "id": 3, "method": "tools/list" }
```

`annotations` tells a client what a tool is safe to call without confirming: read tools carry `{ "readOnlyHint": true, "openWorldHint": false }`, action tools carry `{ "readOnlyHint": false, "destructiveHint": false }`.

### tools/call

```json
{
  "jsonrpc": "2.0", "id": 4, "method": "tools/call",
  "params": { "name": "get_topics", "arguments": { "days": 30 } }
}
```

A successful call returns the tool's data as **JSON text** in a single content item, and, when the result is an object, the same object again as `structuredContent`:

```json
{
  "jsonrpc": "2.0", "id": 4,
  "result": {
    "content": [ { "type": "text", "text": "{\"period\":{\"from\":\"2026-08-18\",\"to\":\"2026-09-16\",\"days\":30},\"topics\":[…]}" } ],
    "structuredContent": { "period": { "from": "2026-08-18", "to": "2026-09-16", "days": 30 }, "topics": ["…"] }
  }
}
```

Read `structuredContent` directly if your client supports it; otherwise parse `content[0].text`.

See [Example responses](/docs/mcp/example-responses/) for what each tool returns.

## Discovery

For a client building its own OAuth flow. Clients that already support MCP sign-in do this automatically.

| Endpoint | Returns |
| --- | --- |
| `/.well-known/oauth-protected-resource` (also at `/.well-known/oauth-protected-resource/mcp`) | Which authorization server protects `/mcp` |
| `/.well-known/oauth-authorization-server` | Grant types (`authorization_code`, `refresh_token`), PKCE (`S256`), scopes (`read`, `act`), and the token and registration endpoints |
| `POST /oauth/register` | Dynamic client registration |

## Errors

### Tool errors

Problems an agent can act on come back as a normal result with `isError: true` and a readable message, never as an empty success:

```json
{
  "jsonrpc": "2.0", "id": 4,
  "result": {
    "content": [ { "type": "text", "text": "Monthly MCP read limit reached (10000). Resets 2026-10-01. Upgrade for a higher limit." } ],
    "isError": true
  }
}
```

These cover a missing plan, the read limit, missing action access, an unknown id, an integration that isn't connected, and a failed third-party call. See [MCP troubleshooting](/docs/mcp/troubleshooting/) for every message.

### JSON-RPC errors

| Code | Message | When |
| --- | --- | --- |
| `-32700` | Parse error | The body isn't valid JSON (HTTP 400). |
| `-32601` | Method not found | An unsupported method. |
| `-32602` | Unknown tool / Invalid arguments | A tool name that doesn't exist, or arguments the tool doesn't accept. |

### HTTP errors

| Status | When |
| --- | --- |
| `401` | Missing or invalid token, revoked token or connection, or a token whose brand no longer exists. Carries `WWW-Authenticate: Bearer realm="GetIntel", resource_metadata="https://app.getintel.ai/.well-known/oauth-protected-resource", error="invalid_token"`, which is how an OAuth-aware client knows to start sign-in. |
| `405` | `GET` or `DELETE` on `/mcp`. The server has no SSE stream; use `POST`. |