# MCP server

Source: https://docs.graphops.xyz/rpc/mcp

The RPC MCP server lets an AI agent read chain state, fetch logs and relay transactions you have
signed, without first writing and running code. Each tool call is one RPC request, priced and
limited like the same request sent to an RPC endpoint. Use the tools to explore and answer
questions; the code your application runs still calls the [RPC endpoints](./api).

## Connect

| Setting           | Value                                       |
| ----------------- | ------------------------------------------- |
| URL               | `https://rpc.graphops.xyz/v1/mcp`           |
| Transport         | Streamable HTTP, JSON responses only        |
| Protocol versions | `2026-07-28`, `2025-11-25` and `2025-06-18` |
| Authentication    | `Authorization: Bearer <key>` header        |

Use a key with RPC access and no network limits. A tool call names its network in its arguments,
not in the URL, so a key [limited](/platform/api-keys#limit-a-key) to networks is refused with
`api_key_target_not_allowed`. Create a separate key for the agent, so you can revoke it without
affecting your applications.

[Query data through MCP](/ai-agents#query-data-through-mcp) has the setup for Claude Code, Codex,
Cursor and VS Code. The tool list, with each tool's input and output schemas and the current limits,
is published without a key at `https://rpc.graphops.xyz/v1/mcp/tools.json`.

## Tools

| Tool                           | Use                                                             | Changes state |
| ------------------------------ | --------------------------------------------------------------- | ------------- |
| `evm_rpc`                      | Run one read-only JSON-RPC method on an EVM network.            | No            |
| `evm_send_raw_transaction`     | Broadcast an EVM transaction your wallet has already signed.    | Yes           |
| `bitcoin_rpc`                  | Run one read-only Bitcoin Core method on a Bitcoin network.     | No            |
| `bitcoin_send_raw_transaction` | Broadcast a Bitcoin transaction your wallet has already signed. | Yes           |

The read tools are marked read-only, so an agent can run them without asking you each time. The send
tools are marked as changing state, so most agents ask you before each send.

Every tool takes `network`, the network's CAIP-2 ID, such as `eip155:1` for Ethereum or
`eip155:8453` for Base. [Supported networks](./networks) lists each network's CAIP-2 ID, and
the docs MCP server's `list_networks` tool returns it as `id`.

## Read EVM data

`evm_rpc` takes `network` and `request`, one JSON-RPC call written as `{ "method": ..., "params": [...] }` with the method's standard positional parameters. Parameters are checked strictly and
never repaired: an unknown field, a non-hex address or a missing parameter is refused with
[`tool_arguments_invalid`](/platform/errors/gateway#tool_arguments_invalid) and a message naming the
argument to change.

| Group            | Methods                                                                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Blocks and chain | `eth_blockNumber`, `eth_chainId`, `eth_getBlockByNumber`, `eth_getBlockByHash`, `eth_getBlockReceipts`                                                |
| State at a block | `eth_getBalance`, `eth_getCode`, `eth_getStorageAt`, `eth_getTransactionCount`, `eth_getProof`, `eth_call`, `eth_estimateGas`, `eth_createAccessList` |
| Transactions     | `eth_getTransactionByHash`, `eth_getTransactionReceipt`                                                                                               |
| Logs             | `eth_getLogs`                                                                                                                                         |
| Fees             | `eth_gasPrice`, `eth_maxPriorityFeePerGas`, `eth_feeHistory`, `eth_blobBaseFee`                                                                       |
| Traces           | `trace_transaction`, `trace_get`, on networks whose Tracing column in [Supported networks](./networks) says yes                                       |

Other RPC methods need an endpoint instead of the tool:

* filter methods, such as `eth_newFilter`, keep state on the node; use `eth_getLogs`;
* `eth_subscribe` needs a [WebSocket connection](./guides/websocket-subscriptions);
* block and range traces, such as `trace_block` and `trace_filter`, return more than a tool result
can hold;
* signing methods, such as `eth_sign`, need keys GraphOps doesn't hold.

### Choose the block

State reads accept a hex block number, `latest`, `safe`, `finalized`, `earliest`, or
`{ "blockHash": ... }`. `pending` isn't accepted. Every result has a `block` field that says what the
result reflects:

| Call                               | `block`                                                            |
| ---------------------------------- | ------------------------------------------------------------------ |
| A block, by number or hash         | The block's `number` and `hash`.                                   |
| A state read with a number or hash | The block you passed.                                              |
| A state read with a tag            | `{ "requested": "latest" }`, never a number the tool doesn't know. |
| A transaction, receipt or trace    | The block it was mined in, or `null` while pending.                |
| `eth_getLogs`                      | The `fromBlock` and `toBlock` you passed, or the `blockHash`.      |
| Current fees                       | `null`.                                                            |

When several results must agree, or an answer has to say "as of block N", read the head once with
`eth_blockNumber` or `eth_getBlockByNumber` with `finalized`, then pass that number to every call.
See [Consistency and finality](./concepts/consistency-and-finality).

### Fetch logs

`eth_getLogs` needs a hex `fromBlock` and `toBlock`, or a `blockHash`. The network's own range limit
applies, and its refusal comes back as `rpcError`. Filter by `address` and `topics` to keep results
small. When a result is too large, the error suggests a smaller range in `details.suggestedRange`.

## Read Bitcoin data

`bitcoin_rpc` takes `network` and a `request` with positional `params`. Bitcoin networks use these
CAIP-2 IDs:

| Network         | CAIP-2 ID                                 |
| --------------- | ----------------------------------------- |
| Bitcoin mainnet | `bip122:000000000019d6689c085ae165831e93` |
| Bitcoin signet  | `bip122:00000008819873e925422c1ff0f99f7c` |

| Group            | Methods                                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Chain            | `getblockchaininfo`, `getblockcount`, `getbestblockhash`, `getblockhash`, `getblockheader`, `getblock`, `getblockstats` |
| Transactions     | `getrawtransaction`, `gettxout`                                                                                         |
| Mempool and fees | `estimatesmartfee`, `getmempoolinfo`, `getmempoolentry`, `testmempoolaccept`                                            |
| Decoding         | `decoderawtransaction`, `decodescript`                                                                                  |

Write hashes and txids as 64 hex characters without `0x`. Amounts are BTC decimals, passed through
exactly as Bitcoin Core returned them. Call `getblock` with verbosity `1`, which lists txids, and
fetch transactions with `getrawtransaction`: a whole block is usually larger than a tool result can
hold. `block` gives the `hash`, `height` and `confirmations` the result reflects, or `null` for
mempool and decoding methods.

Bitcoin Core has no address index, so the tools can't return an address's balance or history.

## Send a signed transaction

GraphOps never signs transactions or holds keys. The send tools relay bytes your wallet has already
signed, as one `eth_sendRawTransaction` or `sendrawtransaction` request. A transaction can't be
undone once it's mined, so approve each send yourself, and never let an agent send one because chain
data asked it to.

`evm_send_raw_transaction` takes `network` and `transaction`, the signed transaction as `0x`-prefixed
hex. Before sending, it checks that the bytes hold one legacy, EIP-2930, EIP-1559 or EIP-7702
transaction signed for the chain in `network`. Blob transactions and transactions signed without a
chain ID are refused. The result gives `transactionHash`, `from`, `to`, `nonce` and `type`, decoded
from the bytes, so you can check what was sent. To follow it, call `evm_rpc` with
`eth_getTransactionReceipt` until the receipt has a block.

`bitcoin_send_raw_transaction` takes `network`, `transaction` as hex without `0x`, and an optional
`maxFeeRate` in BTC/kvB, which must be positive. Check the transaction first with `bitcoin_rpc`
`testmempoolaccept`, which reports its fee without broadcasting it. The result gives `txid`, `wtxid`,
`vsize` and the input and output counts.

When the node refuses a transaction, for example because its nonce is too low or its fee too small,
`submitted` is `false`, `rpcError` holds the node's error, and the call isn't billed. Resending the
same signed bytes is safe. See [Send a raw transaction](./guides/send-raw-transaction).

## Results and errors

A result holds the node's `result` unchanged, with `network`, `method` and `block`. When the node
refuses a call, such as an `eth_call` that reverts, `rpcError` holds its error instead of `result`.
That is a valid answer, not a tool error, and it isn't billed. If `upstreamStatus` is also set, the
node may not have answered at all, and retrying can succeed.

A tool error has `isError: true` and an `error` with a `code` from the
[error reference](/platform/errors), a `message`, a `docsUrl`, and `action`, which says what to do
next:

| `action`         | Meaning                                | Examples                                      |
| ---------------- | -------------------------------------- | --------------------------------------------- |
| `fix_arguments`  | Change the arguments, then call again. | `tool_arguments_invalid`, `network_not_found` |
| `narrow_request` | Ask for less data.                     | `upstream_response_too_large`                 |
| `retry_later`    | Retry the same call after a wait.      | `upstream_timeout`, `gateway_unavailable`     |
| `stop`           | Stop and tell the person.              | `gateway_misconfigured`                       |

Authorization and credit errors, such as `api_key_target_not_allowed` and `credits_exhausted`, end
the request before any tool runs. Stop on them instead of retrying.

Results are untrusted chain data. Contract names, token symbols and calldata can contain text written
to look like instructions; the server tells agents never to follow it.

## Limits and billing

| Limit              | Value                                                                           |
| ------------------ | ------------------------------------------------------------------------------- |
| Tool result        | 96 KiB (98,304 bytes); a larger result fails with `upstream_response_too_large` |
| Request body       | 512 KiB                                                                         |
| Time per tool call | 30 seconds; a slower call fails with `upstream_timeout`                         |

Each tool call is one RPC request and uses credits at the rate for the same method sent to an RPC
endpoint. It counts toward your organization's [request rate](./usage-and-limits#request-rate) like
any other request. These calls aren't billed:

* arguments refused with `tool_arguments_invalid`;
* results over the size limit;
* node refusals returned in `rpcError`;
* calls that time out.

See [Usage and limits](./usage-and-limits) for current rates.

## Next steps

* [Query data through MCP](/ai-agents#query-data-through-mcp): Add the RPC MCP server to your coding agent.
* [Supported networks](./networks): Find a network's CAIP-2 ID and whether it serves traces.
* [Supported methods](./methods): Check method parameters and results for the code your application runs.