# MCP server

PIT provides a Model Context Protocol endpoint at `POST /mcp`. It gives AI agents four read-only tools to query point-in-time data as of any past timestamp. The endpoint is hosted, so you do not need to install local software.

Reference documentation. Updated 2026-08-26 against the corpus described on [coverage](https://pit.aqx.llc/docs/coverage).

## Endpoint

- **URL**: `https://api.pit.aqx.llc/mcp`
- **Transport**: Streamable HTTP. JSON-RPC 2.0 over HTTP `POST`. Supports `text/event-stream` when requested by the client.
- **Auth**: Pass `Authorization: Bearer pit_live_…` using your REST API key. Requests without a key access the public sample.
- **Local**: `http://127.0.0.1:8080/mcp`

Each tool call executes one `/v1` request on the server. MCP responses use the same JSON envelope and error codes as `curl` requests, and each call counts as one request toward your plan rate limit.

## Claude Code

**terminal**

```
$ claude mcp add --transport http pit https://api.pit.aqx.llc/mcp --header "Authorization: Bearer pit_live_..."
```

If you omit `--header`, the connection defaults to the public sample. Run `claude mcp list` to view configured servers, and `claude mcp remove pit` to remove the server.

## Claude.ai

In Settings, open Connectors, select **Add custom connector**, and paste this URL.

**custom connector URL**

```
https://api.pit.aqx.llc/mcp
```

Claude.ai custom connectors support OAuth or unauthenticated connections. PIT does not currently support OAuth, so Claude.ai connections use the public sample where every row has `sample: true`. To query the full corpus, use a client that can send custom headers, such as Claude Code, Cursor, or a custom application.

## Cursor

Add this configuration to `~/.cursor/mcp.json` for global access across all projects, or to `.cursor/mcp.json` inside a specific project.

**mcp.json**

```
{
  "mcpServers": {
    "pit": {
      "url": "https://api.pit.aqx.llc/mcp",
      "headers": {
        "Authorization": "Bearer pit_live_..."
      }
    }
  }
}
```

## The four tools

| Tool | Answers | Same as |
| --- | --- | --- |
| `pit_query` | The filings that were knowable at one instant. | `GET /v1/news` |
| `pit_diff` | The rows that became knowable between two instants. | `GET /v1/news/diff` |
| `pit_coverage` | Which source-days we mined, and how completely. | `GET /v1/coverage` |
| `pit_meta` | Corpus version, sources, certified span, plans. | `GET /v1/meta` |

All four tools are read-only and return the [standard envelope](https://pit.aqx.llc/docs/api) as JSON text. Check `count` before parsing `results`. A number indicates a successful query. A JSON null indicates that the requested window includes uncertified dates. In that case, the data is unknown, and `coverage.missing` lists those dates.

## pit_query arguments

| Argument | What it does |
| --- | --- |
| `as_of` | The instant you are asking about, RFC3339 UTC with a literal `Z`. Some clients call this `known_at`; it is the same value. Required once you send a key. |
| `visible_by` | Which timestamp `as_of` is compared against: `published_at` (default), `available_at`, or `committed_at`. See [timestamps](https://pit.aqx.llc/docs/clocks). |
| `ticker` | Resolved to the CIKs (SEC company numbers) that held the symbol at `as_of`, so a company that renamed later still comes back. Send `ticker` or `cik`, not both. |
| `cik` | SEC Central Index Key. Needs a key. |
| `source` | One source id, such as `sec.edgar`. `pit_meta` lists them. |
| `lane` | `certified_pit` for the mined history, `forward_first_seen` for the live tape's first sighting. |
| `limit` | 1 to 1000, default 100. Anything larger returns an error. |
| `cursor` | `next_cursor` from the previous page. |

`pit_diff` accepts the same filter arguments as `pit_query`, but uses `as_of_start` and `as_of_end` instead of `as_of`. `pit_coverage` accepts `source`, `date`, `as_of`, `limit`, and `cursor`. `pit_meta` takes no arguments.

## Without a key

Without an API key, tools query the public sample dataset: SVB (`SIVB`), Apple (`AAPL`), and Meta (`META`, or `FB` before the rename) on the certified dates used in the [demo](https://pit.aqx.llc/demo). Every returned row includes `sample: true`. Querying any other ticker returns an error listing the three supported tickers.

A valid API key gives access to the full corpus at your plan's rate limit: 60 requests per minute on Researcher, or 300 on Power. If the key is rejected, the server returns JSON-RPC error `-32001` containing the standard REST `unauthorized` envelope.

Queries are refused if a required timestamp is missing, `limit` exceeds 1000, the `source` is invalid, or the window hits a coverage gap. In these cases, the tool returns a response with `isError` set to true, includes the full envelope in the text, and explains the issue in the message.

## Try it with curl

**no key, sample tier — 200 · count 1**

```
$ curl -s -X POST https://api.pit.aqx.llc/mcp \
    -H 'Content-Type: application/json' \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
         "params":{"name":"pit_query","arguments":{"ticker":"SIVB"}}}'
```

The text block inside `result.content` contains the envelope: `as_of` `2023-03-10T23:59:59Z`, `visible_by` `published_at`, `status` `ok`, `count` 1, and one SVB 8-K filing accepted at `2023-03-10T22:23:03Z` marked with `sample: true`.

## Protocol details

- **Revisions**: Supported versions are `2025-06-18` and `2025-03-26`. If a client requests either version, the server responds with that version. All other requests default to `2025-06-18`.
- **Methods**: `initialize`, `notifications/initialized`, `ping`, `tools/list`, `tools/call`.
- **Response mode**: Responses use `application/json`, or `text/event-stream` when prioritized in the `Accept` header. An SSE response sends a single `event: message` frame and closes the stream.
- **Sessions**: The server is stateless. It echoes back any provided `MCP-Session-Id` header, but never generates one.
- **Other methods**: `GET /mcp` and `DELETE /mcp` return 405. The server does not support persistent streams or session termination.

## Not supported yet

OAuth authentication is not supported. The server advertises tool `capabilities` only; MCP resources and prompts are not available. There are no MCP tools for the `/v1/stream` live tape, `/v1/files`, or `/v1/mapping`.