The Graph MCP - Nile Markets

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.

Claude Desktop
Cursor

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"
      }
    }
  }
}

Replace 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"
      }
    }
  }
}

After connecting, add 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 13 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
ProtocolState	Mutable	Operating mode (NORMAL, DEGRADED, REDUCE_ONLY, PAUSED)
DailyStats	Mutable	Daily volume, fees, position opens/closes, and pool PnL
OracleRound	Immutable	Published forward price rounds — dedupe by `fixingTimestamp` sorted by `publishTime` desc for latest
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

Mutable entities reflect current state and are updated over time. Immutable entities are append-only event records that never change after creation.

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
  }
}

Get current pool metrics:

{
  poolState(id: "pool") {
    totalAssets
    totalShares
    sharePrice
    utilization
    longExposure
    shortExposure
  }
}

Query daily stats for the past week:

{
  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

Use Graph MCP when you need custom queries, cross-entity joins, or aggregations that the typed tools don’t support — for example, filtering positions by multiple criteria simultaneously or computing custom analytics across entities. Use Nile MCP when you want structured interactions with response formatting, real-time RPC data (current prices, live PnL), or write operation calldata. The Nile MCP server is at 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.

​Prerequisites

​Setup

​Available Entities

​Example Queries

​Graph MCP vs Nile MCP

Prerequisites

Setup

Available Entities

Example Queries

Graph MCP vs Nile MCP