Subgraph MCP Server

Permite que LLMs interajam com Subgraphs disponíveis na The Graph Network.

GitHub
8
Experimente este MCPPatrocinado

Documentação

Subgraph MCP Server

Um servidor Model Context Protocol (MCP) que permite que LLMs interajam com Subgraphs disponíveis na The Graph Network.

Recursos

  • Obtenha o schema GraphQL para qualquer subgraph/deployment
  • Execute consultas GraphQL contra qualquer subgraph/deployment
  • Encontre os principais deployments de subgraph para um endereço de contrato em uma chain específica
  • Pesquise subgraphs por palavra-chave
  • Obtenha o volume de consultas de 30 dias para deployments de subgraph
  • Suporta recursos, ferramentas e prompts do MCP
  • Pode ser executado em modo STDIO ou como um servidor SSE (Server-Sent Events)

Uso

O servidor subgraph-mcp oferece duas formas principais de interagir com a The Graph Network:

  1. Conectando-se ao Serviço MCP Hospedado Remotamente (Recomendado para a maioria dos usuários)
  2. Compilando e Executando o Servidor Localmente

Conectando-se ao Serviço MCP Hospedado Remotamente

Esta é a forma mais rápida de começar. Você pode configurar seu cliente MCP (ex.: Claude Desktop) para se conectar ao nosso serviço subgraph-mcp hospedado.

Requisitos

  • Uma chave de API Gateway para a The Graph Network.

Configuração

Adicione o seguinte ao arquivo de configuração do seu cliente (ex.: claude_desktop_config.json):

{
  "mcpServers": {
    "subgraph-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "https://subgraphs.mcp.thegraph.com/sse"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_GATEWAY_API_KEY" // <-- Replace with your actual key
      }
    }
  }
}

Substitua YOUR_GATEWAY_API_KEY pela sua chave de API Gateway real. Após adicionar a configuração, reinicie seu cliente MCP.

Após a configuração, você pode ir diretamente para as seções "Ferramentas Disponíveis" ou "Consultas em Linguagem Natural" para aprender como interagir com o serviço.

Compilando e Executando o Servidor Localmente

Esta opção é para usuários que preferem compilar, executar e potencialmente modificar o servidor em sua própria máquina.

Requisitos (para Execução Local)

  • Rust (versão estável mais recente recomendada: 1.75+).
    Você pode instalá-lo usando o seguinte comando no macOS, Linux ou outros sistemas similares ao Unix: \ 
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    Siga as instruções na tela. Para outras plataformas, consulte o guia oficial de instalação do Rust.
  • Uma chave de API Gateway para a The Graph Network.

Instalação (para Execução Local)

# Clone the repository
git clone git@github.com:graphops/subgraph-mcp.git
cd subgraph-mcp

# Build the project
cargo build --release

Configuração (para Execução Local)

Adicione o seguinte ao arquivo de configuração do seu cliente (ex.: claude_desktop_config.json):

{
  "mcpServers": {
    "subgraph-mcp": {
      "command": "/path/to/your/subgraph-mcp/target/release/subgraph-mcp", // <-- Replace this with the actual path!
      "env": {
        "GATEWAY_API_KEY": "YOUR_GATEWAY_API_KEY" // <-- Replace with your actual key
      }
    }
  }
}

Você precisa substituir /path/to/subgraph-mcp pelo caminho absoluto para o binário compilado que você construiu na etapa de Instalação.

Encontrando o caminho do comando:

Após executar cargo build --release, o executável normalmente estará localizado em target/release/subgraph-mcp dentro do diretório do seu projeto (subgraph-mcp).

  1. Navegue até o diretório subgraph-mcp no terminal.
  2. Execute pwd (print working directory) para obter o caminho completo para o diretório subgraph-mcp.
  3. Combine a saída de pwd com /target/release/subgraph-mcp.

Por exemplo, se pwd retornar /Users/user/subgraph-mcp, o caminho completo do comando seria /Users/user/subgraph-mcp/target/release/subgraph-mcp.

Após adicionar a configuração, reinicie o Claude Desktop.

Configuração de Timeout de Requisição (para Execução Local)

O servidor inclui configurações de timeout ajustáveis para requisições HTTP ao Gateway da The Graph. Isso ajuda a lidar com consultas GraphQL complexas que podem levar mais tempo para serem executadas.

Comportamento Padrão

Por padrão, o servidor usa um timeout de 120 segundos para todas as requisições HTTP ao Gateway da The Graph. Isso proporciona um bom equilíbrio entre permitir que consultas complexas sejam concluídas e evitar travamentos indefinidos.

Configuração Personalizada de Timeout

Você pode personalizar o timeout de várias formas:

Opção 1: Variável de Ambiente (Recomendada)

Defina a variável de ambiente SUBGRAPH_REQUEST_TIMEOUT_SECONDS:

export SUBGRAPH_REQUEST_TIMEOUT_SECONDS=300  # 5 minutes

Para configuração do Claude Desktop:

{
  "mcpServers": {
    "subgraph-mcp": {
      "command": "/path/to/subgraph-mcp",
      "env": {
        "GATEWAY_API_KEY": "YOUR_GATEWAY_API_KEY",
        "SUBGRAPH_REQUEST_TIMEOUT_SECONDS": "300"
      }
    }
  }
}

Opção 2: Configuração Programática (para desenvolvedores)

Ao construir aplicações com a biblioteca do servidor:

use std::time::Duration;
use subgraph_mcp::SubgraphServer;

// Use default timeout (120 seconds)
let server = SubgraphServer::new();

// Use custom timeout
let server = SubgraphServer::with_timeout(Duration::from_secs(300));

Nota: Timeouts muito longos (>5 minutos) devem ser usados com cautela, pois podem impactar a capacidade de resposta geral da aplicação.

Importante: O Claude Desktop pode não utilizar automaticamente os recursos do servidor. Para garantir o funcionamento adequado, adicione manualmente o recurso Subgraph Server Instructions ao seu contexto de chat clicando no menu de contexto e adicionando o recurso.

Ferramentas Disponíveis

O servidor expõe as seguintes ferramentas:

  • search_subgraphs_by_keyword: Pesquisa subgraphs por palavra-chave em seus nomes de exibição. Ordenado por sinal. Retorna os 10 principais resultados se o total de resultados ≤ 100, ou a raiz quadrada do total caso contrário.
  • get_deployment_30day_query_counts: Obtém a contagem agregada de consultas nos últimos 30 dias para múltiplos deployments de subgraph (usando seus hashes IPFS), ordenados pela contagem de consultas.
  • get_schema_by_deployment_id: Obtém o schema GraphQL para um deployment específico de subgraph usando seu deployment ID (ex.: 0x...).
  • get_schema_by_subgraph_id: Obtém o schema GraphQL para o deployment atual associado a um subgraph ID (ex.: 5zvR82...).
  • get_schema_by_ipfs_hash: Obtém o schema GraphQL para um deployment específico de subgraph usando o hash IPFS do seu manifesto (ex.: Qm...).
  • execute_query_by_deployment_id: Executa uma consulta GraphQL contra um deployment de subgraph específico e imutável usando seu deployment ID (ex.: 0x...).
  • execute_query_by_subgraph_id: Executa uma consulta GraphQL contra o deployment mais recente associado a um subgraph ID (ex.: 5zvR82...).
  • execute_query_by_ipfs_hash: Executa uma consulta GraphQL contra um deployment de subgraph específico e imutável usando seu hash IPFS (ex.: Qm...).
  • get_top_subgraph_deployments: Obtém os 3 principais deployments de subgraph que indexam um determinado endereço de contrato em uma chain específica, ordenados por taxas de consulta.

Consultas em Linguagem Natural

Uma vez conectado a um LLM com este servidor MCP, você pode fazer perguntas em linguagem natural.

Importante: O Claude Desktop pode não utilizar automaticamente os recursos do servidor. Para garantir o funcionamento adequado, adicione manualmente o recurso Subgraph Server Instructions ao seu contexto de chat clicando no menu de contexto e adicionando o recurso.

Exemplo de uso no Claude (ou outros clientes MCP), assumindo que você adicionou Subgraph Server Instructions ao seu prompt:

User: List the 20 most recently registered .eth names.

Assistant (after `search_subgraphs_by_keyword`, `get_deployment_30day_query_counts` and other tool usage):
Perfect! I've successfully retrieved the 20 most recently registered .eth names using the ENS subgraph, which has 68.1 million queries in the last 30 days, making it the most active and reliable source for ENS data.
Here are the 20 most recently registered .eth names:

...

O LLM automaticamente irá:

  1. Seguir as Instruções do Servidor Subgraph.
  2. Usar search_subgraphs_by_keyword para encontrar subgraphs candidatos.
  3. Usar get_deployment_30day_query_counts para verificar a atividade e auxiliar na seleção.
  4. Usar get_top_subgraph_deployments se um endereço de contrato for fornecido.
  5. Buscar e entender o schema do subgraph usando a ferramenta get_schema_by_* apropriada.
  6. Converter sua pergunta em uma consulta GraphQL apropriada.
  7. Executar a consulta usando a ferramenta execute_query_by_* correta com base no tipo de identificador e no deployment ativo confirmado.
  8. Apresentar os resultados em um formato legível.

Prompts

O servidor fornece prompts predefinidos para a maioria das ferramentas (conforme descoberto via list_prompts do MCP):

  • get_schema_by_deployment_id: Obter o schema para um deployment ID.
  • get_schema_by_subgraph_id: Obter o schema para um subgraph ID.
  • get_schema_by_ipfs_hash: Obter o schema para um hash IPFS.
  • execute_query_by_deployment_id: Executar uma consulta GraphQL contra um deployment ID.
  • execute_query_by_subgraph_id: Executar uma consulta GraphQL contra um subgraph ID.
  • execute_query_by_ipfs_hash: Executar uma consulta GraphQL contra um hash IPFS.
  • get_top_subgraph_deployments: Obter os principais subgraphs para um contrato em uma chain específica.

Recursos

O servidor expõe um recurso:

  • graphql://subgraph: Fornece o Subgraph Server Instructions detalhado usado pelo LLM, incluindo o fluxo de trabalho para diferentes objetivos do usuário (consulta de endereço, encontrar subgraphs para um contrato, consultar por ID, obter schema) e notas importantes de uso.

Abaixo está uma referência para o Subgraph Server Instructions:

**Interacting with The Graph Subgraphs**
**IMPORTANT: ALWAYS verify query volumes using `get_deployment_30day_query_counts` for any potential subgraph candidate *before* selecting or querying it. This step is NON-OPTIONAL. Failure to do so may result in using outdated or irrelevant data.**
**Follow this sequence strictly:**
1.  **Analyze User Request:**
    *   Identify the **protocol name** (e.g., "Uniswap", "Aave", "ENS").
    *   Note any specific **version** or **blockchain network** mentioned by the user.
    *   Determine the **goal**: Query data? Get schema?
2.  **Initial Search & Preliminary Analysis:**
    *   Use `search_subgraphs_by_keyword` with the most generic term for the protocol (e.g., if "Uniswap v3 on Ethereum", initially search only for "Uniswap").
    *   Examine `displayName` and other metadata in the search results for version and network information.
3.  **Mandatory Query Volume Check & Clarification (If Needed):**
    *   **ALWAYS** extract the IPFS hashes (`ipfsHash`) for all potentially relevant subgraphs identified in Step 2.
    *   **ALWAYS** use `get_deployment_30day_query_counts` for these IPFS hashes.
    *   **If Ambiguous (Multiple Versions/Chains with significant volume):**
        *   Present a summary to the user, **including the 30-day query counts for each option**. For example: "I found several Uniswap subgraphs. Uniswap v3 on Ethereum is the most active (X queries last 30 days). I also see Uniswap v2 on Ethereum (Y queries) and Uniswap v3 on Arbitrum (Z queries). Which specific version and network are you interested in?"
    *   **If Still Unclear (Information Missing and Not Inferable even with query volumes):**
        *   If version/chain information is genuinely missing from search results and user input, and query volumes don't offer a clear path (e.g. all relevant subgraphs have very low or no volume), ask for clarification directly. Example: "I found several subgraphs for 'ExampleProtocol', but none have significant query activity. Could you please specify the version and blockchain network you're interested in?"
    *   **Do NOT proceed to Step 4 without completing this query volume verification.**
4.  **Select Final Subgraph (Post Query Volume Check & Clarification):**
    *   After the keyword search, mandatory query volume check, and any necessary clarification, you should have a clear target protocol, version, and network.
    *   Identify all candidate subgraphs from your Step 2 `search_subgraphs_by_keyword` results that match these clarified criteria.
    *   **If there is more than one such matching subgraph:**
        *   You should have already fetched their query counts in Step 3.
        *   **Select the subgraph with the highest `total_query_count`** among them.
    *   **If only one subgraph precisely matches the criteria**, that is your selected subgraph.
    *   When presenting your chosen subgraph or asking for final confirmation before querying, **ALWAYS state its 30-day query volume** to demonstrate this check has been performed. For example: "I've selected the 'Uniswap v3 Ethereum' subgraph, which has X queries in the last 30 days. Shall I proceed to get its schema?"
    *   If the selected subgraph's query count is very low (and this wasn't already discussed during clarification), briefly inform the user.
5.  **Execute Action Using the Identified Subgraph:**
    *   **Identify the ID Type:** (Subgraph ID, Deployment ID, or IPFS Hash - note that `search_subgraphs_by_keyword` returns `id` for Subgraph ID and `ipfsHash` for current deployment's IPFS hash).
    *   **Determine the Correct Tool based on Goal & ID Type:**
        *   **Goal: Query Data**
            *   Subgraph ID (`id` from search) → `execute_query_by_subgraph_id`
            *   Deployment ID (0x...) → `execute_query_by_deployment_id`
            *   IPFS Hash (`ipfsHash` from search) → `execute_query_by_ipfs_hash`
        *   **Goal: Get Schema**
            *   Subgraph ID → `get_schema_by_subgraph_id`
            *   Deployment ID → `get_schema_by_deployment_id`
            *   IPFS Hash → `get_schema_by_ipfs_hash`
    *   **Write Clean GraphQL Queries:** Simple structure, omit 'variables' if unused, include only essential fields.
**Special Case: Contract Address Lookup**
*   ONLY when a user explicitly provides a **contract address** (0x...) AND asks for subgraphs related to it:
    *   Identify the blockchain network for the address (ask user if unclear).
    *   Use `get_top_subgraph_deployments` with the provided contract address and chain name.
    *   Process and use the resulting IPFS hashes as needed. **Crucially, before using any of these IPFS hashes for querying, first use `get_deployment_30day_query_counts` with their IPFS hashes to verify recent activity.**
**ID Type Reference:**
*   **Subgraph ID**: Typically starts with digits and letters (e.g., 5zvR82...)
*   **Contract Address**: A shorter hexadecimal string, typically 42 characters long including the "0x" prefix (e.g., 0x1a3c9b1d2f0529d97f2afc5136cc23e58f1fd35b).
*   **Deployment ID**: A longer hexadecimal string, typically 66 characters long including the "0x" prefix (e.g., 0xc5b4d246cf890b0b468e005224622d4c85a8b723cc0b8fa7db6d1a93ddd2e5de). Use length to distinguish from a Contract Address.
*   **IPFS Hash**: Typically starts with Qm... For the purpose of `get_deployment_30day_query_counts`, use the \'IPFS Hash\' (Qm...).
*   Note `search_subgraphs_by_keyword` and `get_top_subgraph_deployments` returns `ipfsHash`.

**Best Practices:**
*   When using GraphQL, if unsure about the structure, first get the schema to understand available entities and fields.
*   Create focused queries that only request necessary fields.
*   For paginated data, use appropriate limit parameters.
*   Use variables for dynamic values in queries.

Monitoramento

O servidor expõe métricas Prometheus para monitorar seu desempenho e comportamento.

Endpoint de Métricas

Ao executar em modo SSE, um servidor de métricas é iniciado em uma porta separada.

  • Endpoint: /metrics
  • Porta Padrão: 9091

Você pode configurar a porta e o host do servidor de métricas usando as variáveis de ambiente METRICS_PORT e METRICS_HOST.

Métricas Expostas

As seguintes métricas específicas da aplicação são expostas:

  • mcp_tool_calls_total{tool_name, status}: Um contador para o número de chamadas de ferramentas MCP.
    • tool_name: O nome da ferramenta MCP sendo chamada (ex.: get_schema_by_deployment_id).
    • status: O resultado da chamada (success ou error).
  • mcp_tool_call_duration_seconds{tool_name}: Um histograma da duração das chamadas de ferramentas MCP.
  • gateway_requests_total{endpoint_type, status}: Um contador para requisições de saída ao Gateway da The Graph.
    • endpoint_type: O tipo de consulta ou endpoint sendo acessado (ex.: get_schema_by_deployment_id, subgraphs/id).
    • status: O resultado da requisição (success ou error).
  • gateway_request_duration_seconds{endpoint_type}: Um histograma da duração das requisições ao Gateway.

Além disso, a biblioteca axum-prometheus fornece métricas padrão de requisições HTTP para o próprio servidor de métricas (prefixadas com http_).

Solução de Problemas

Erros de Timeout de Requisição

Se você encontrar erros de "Request timed out" ou "MCP error -32001", isso normalmente indica que as consultas GraphQL estão levando mais tempo do que o timeout configurado para serem concluídas.

Soluções:

Se você estiver executando sua própria instância local do servidor:

  1. Aumente o timeout usando a variável de ambiente SUBGRAPH_REQUEST_TIMEOUT_SECONDS: 
    export SUBGRAPH_REQUEST_TIMEOUT_SECONDS=300  # 5 minutes

Se você estiver usando o serviço hospedado remoto:

  1. Entre em contato com o suporte - As configurações de timeout são gerenciadas pelo serviço hospedado e não podem ser personalizadas pelos usuários finais.

Para todos os usuários:

  1. Verifique a complexidade da consulta - Consultas muito complexas com grandes conjuntos de resultados podem precisar de timeouts mais longos ou otimização da consulta.

  2. Verifique o status do Gateway da The Graph - Problemas ocasionais de timeout podem ser devidos a problemas temporários de desempenho do Gateway.

Timeout Padrão: Instâncias locais do servidor usam um timeout de 120 segundos por padrão (aumentado de 30 segundos em versões anteriores). As configurações de timeout do serviço hospedado remoto podem ser diferentes.

Problemas Comuns

  • "API key not found": Certifique-se de que sua variável de ambiente GATEWAY_API_KEY esteja configurada corretamente
  • "Configuration error": Verifique se sua chave de API Gateway é válida e possui as permissões apropriadas
  • Connection refused: Verifique se o servidor está em execução e acessível na porta configurada

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Apache-2.0