# API and MCP

[filecoin-api](https://api.filecoin.cloud) serves read-only Filecoin data: storage providers, data sets, pieces, Filecoin Pay rails, and session keys. It reads from an indexer of the Filecoin chain, so its data trails the chain. `/health` reports the latest indexed block. It cannot store, delete, or sign anything.

The interactive reference is at [`/docs`](https://api.filecoin.cloud/docs), and the OpenAPI 3.1 document is at [`/openapi.json`](https://api.filecoin.cloud/openapi.json).

## Routes

`GET /openapi.json` lists every route and its filters, and `POST /mcp` is the MCP server, which also has its own host, `https://mcp.filecoin.cloud`. `GET /health` reports the latest indexed block per network, and [`GET /get/{cid}`](#retrieval) redirects to where content can be retrieved. Every data route starts with the network, `/calibration/...` or `/mainnet/...`, and reads one of: indexer status, storage providers, data sets and their pieces, pieces by owner or PieceCID, Filecoin Pay rails and their settlements, and session keys and their history.

Conventions:

- **Owner** is the address that pays for a data set.
- **Big numbers**, such as IDs, amounts, and epochs, are decimal strings.
- **Pagination** uses `limit` (1 to 200, default 50) and an opaque `cursor`. Each response looks like `{ data, nextCursor }`.
- **Errors** look like `{ error: { code, message } }`.
- **Operation IDs**, such as `listDataSets` and `retrieve`, name every operation in the OpenAPI document, for function calling and generated clients.

## Retrieval

`GET /get/{cid}?network=mainnet&browser=false` redirects to where the content can be fetched. It never proxies the bytes. `network` defaults to `mainnet`.

| CID | `browser` | Redirect |
| --- | --- | --- |
| PieceCID v2 (`bafkzcib…`) | `false` or absent | The provider's `/piece/{cid}` |
| PieceCID v2 (`bafkzcib…`) | `true` | `https://inbrowser.link/ipfs/{root}` when the piece is a folder, otherwise the provider's `/piece/{cid}` |
| Other CID (IPFS content) | `false` or absent | The provider's `/ipfs/{cid}` |
| Other CID (IPFS content) | `true` | `https://inbrowser.link/ipfs/{cid}` |

`provider={id}` names a provider to redirect to when the indexer has no copy yet. It covers the time between a provider receiving a piece and the indexer seeing the commit. An indexed copy always wins over it. `filecoin put` adds it to the early links it prints before the commit confirms.

Legacy v1 PieceCIDs (`baga…`) and strings that aren't CIDs return `400`. If no live copy exists and no `provider` applies, the response is `404`. When several providers store the content, the route prefers endorsed providers, then approved ones, then the oldest copy.

## MCP server

The MCP server at `https://mcp.filecoin.cloud` offers one read-only tool for each data route. Each tool requires a `network` argument.

| Tool | Reads |
| --- | --- |
| `get_status` | Indexer progress |
| `list_providers`, `get_provider` | Storage providers |
| `list_data_sets`, `get_data_set` | Data sets |
| `list_data_set_pieces`, `get_piece`, `list_pieces` | Pieces |
| `list_rails`, `get_rail`, `list_rail_settlements` | Filecoin Pay rails and settlements |
| `list_session_keys`, `list_session_key_events` | Session keys and their history |

[Agents](/agents#mcp-server) shows how to add it to an agent.

## Limits

- **Rate limits.** 120 requests a minute per IP for the REST API, and 60 for MCP. Over the limit, requests get `429` with `Retry-After`.
- **Caching.** Data reads are not cached by browsers, so every read returns the latest indexed data.
- **No authentication.** Every route is public and read-only.