The Graph hosts an MCP server that exposes any deployed subgraph — including Nile Markets — as a tool for AI agents. Instead of typed tools, you get raw GraphQL access to all 14 indexed entities with full filtering, pagination, and aggregation.
Prerequisites
You need a Graph API key for all usage (including testnet). Create one at thegraph.com/studio.
Setup
The Graph MCP uses SSE transport, which requires mcp-remote as a local proxy. The server name (nile-graph below) is a local alias you choose — it’s how your agent identifies this MCP connection.
Add to your claude_desktop_config.json (Settings > Developer > Edit Config):{
"mcpServers": {
"nile-graph": {
"command": "npx",
"args": [
"mcp-remote",
"--header",
"Authorization:${AUTH_HEADER}",
"https://subgraphs.mcp.thegraph.com/sse"
],
"env": {
"AUTH_HEADER": "Bearer YOUR_GRAPH_API_KEY"
}
}
}
}
YOUR_GRAPH_API_KEY with your key from Subgraph Studio, then restart Claude Desktop. Add to .cursor/mcp.json:{
"mcpServers": {
"nile-graph": {
"command": "npx",
"args": [
"mcp-remote",
"--header",
"Authorization:${AUTH_HEADER}",
"https://subgraphs.mcp.thegraph.com/sse"
],
"env": {
"AUTH_HEADER": "Bearer YOUR_GRAPH_API_KEY"
}
}
}
}
graphql://subgraph as a resource in your agent’s context to activate the MCP tools. You specify which subgraph to query at query time — by deployment ID, subgraph ID, or keyword search.
The Graph MCP does not support direct HTTP transport. You must use the npx mcp-remote proxy as shown above. Claude Code’s claude mcp add --transport http will not work for this server.
Available Entities
The Nile Markets subgraph indexes 14 entity types across protocol state, positions, oracle data, and analytics.
| Entity | Type | Description |
|---|
| Position | Mutable | Open and closed FX forward positions with PnL, margin, and lifecycle state |
| Account | Mutable | Trader margin accounts with collateral, locked amounts, and position counts |
| PoolState | Mutable | Liquidity pool metrics — TVL, utilization, share price, exposure |
| OracleState | Mutable | Current spot price, forward prices, and oracle validity |
| ProtocolState | Mutable | Operating mode (NORMAL, DEGRADED, REDUCE_ONLY, PAUSED) |
| DailyStats | Mutable | Daily volume, fees, position opens/closes, and pool PnL |
| OracleRound | Mutable | Published forward price rounds per tenor |
| TxFeeAccumulator | Mutable | Running fee totals by category |
| PoolTransaction | Immutable | Vault deposit and withdrawal events |
| FeeEvent | Immutable | Individual fee charges (trading, liquidation, termination, oracle) |
| FixingPrice | Immutable | Recorded spot prices at maturity for settlement |
| VaultEvent | Immutable | ERC-4626 vault share mint/burn events |
| ModeTransition | Immutable | Protocol mode change history |
| PositionReduction | Immutable | Partial position reduction events |
Example Queries
Once connected, your agent can run arbitrary GraphQL against the Nile Markets subgraph.
Fetch all open positions for an account:
{
positions(
where: { account: "0xabc...", status: "OPEN" }
orderBy: openedAt
orderDirection: desc
first: 25
) {
id
side
tenor
notional
entryStrike
margin
openedAt
}
}
{
poolState(id: "pool") {
totalAssets
totalShares
sharePrice
utilization
longExposure
shortExposure
}
}
{
dailyStats(
orderBy: date
orderDirection: desc
first: 7
) {
date
volume
fees
positionsOpened
positionsClosed
}
}
Graph MCP vs Nile MCP
Both give AI agents access to Nile Markets data. They serve different use cases.
| Capability | Graph MCP | Nile MCP |
|---|
| Access method | Raw GraphQL queries | 22 typed tools |
| Data source | Subgraph only | Subgraph + RPC |
| Write operations | No | 8 tools (unsigned calldata) |
| Real-time prices | No (subgraph lag) | Yes (RPC reads) |
| Response format | Raw GraphQL JSON | Structured envelope with protocol metadata |
| Custom queries | Full GraphQL flexibility | Fixed tool schemas |
| Setup | Graph API key required + npx mcp-remote proxy | No auth required (M2 testnet) |
| Entity access | All 14 entities, any field combination | Curated subsets per tool |
mcp.nilemarkets.com/api/mcp — see MCP Server for setup.
You can use both servers simultaneously. Use Nile MCP for standard operations and fall back to Graph MCP for custom analytics queries.
