graphprotocol · benface · Nov 20, 2025 · Nov 19, 2025 · Nov 19, 2025 · Nov 19, 2025
@@ -18,12 +18,13 @@ Create or edit your `claude_desktop_config.json` file.
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 - Linux: `.config/Claude/claude_desktop_config.json`
 
+**REST-based MCP**
 ```json label="claude_desktop_config.json"
 {
   "mcpServers": {
     "token-api": {
       "command": "npx",
-      "args": ["@pinax/mcp", "--sse-url", "https://token-api.mcp.thegraph.com/sse"],
+      "args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/"],
       "env": {
         "ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
       }
@@ -32,9 +33,43 @@ Create or edit your `claude_desktop_config.json` file.
 }
 ```
 
+**SQL-based MCP**
+```json label="claude_desktop_config.json"
+{
+  "mcpServers": {
+    "token-api": {
+      "command": "npx",
+      "args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/sql"],
+      "env": {
+        "ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
+      }
+    }
+  }
+}
+```
+
+> [!NOTE]
+> The previous `--sse-url` option is deprecated, use `--remote-url`.
+
 ## Troubleshooting
 
-To enable logs for the MCP, add the option `"--verbose", "true"` under `"args"`.
+To enable logs for troubleshooting the MCP, add the option `"--verbose", "true"` under `"args"`.
+
+```json label="claude_desktop_config.json"
+{
+  "mcpServers": {
+    "token-api": {
+      "command": "npx",
+      "args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/", "--verbose", "true"],
+      "env": {
+        "ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
+      }
+    }
+  }
+}
+```
+
+Logs are available under `logs/mcp.log` and `/logs/mcp-server-token-api.log` inside the folder of your Claude configuration file.
 
 ### ENOENT
 

@@ -18,24 +18,57 @@ Create or edit your `cline_mcp_settings.json` file.
 
 > **MCP Servers** > **Installed** > **Configure MCP Servers**
 
+**REST-based MCP**
 ```json label="cline_mcp_settings.json"
 {
   "mcpServers": {
-    "mcp-pinax": {
+    "token-api": {
       "command": "npx",
-      "args": ["@pinax/mcp", "--sse-url", "https://token-api.mcp.thegraph.com/sse"],
+      "args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/"],
       "env": {
-        "ACCESS_TOKEN": "<JWT Token from thegraph.market>"
+        "ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
       }
     }
   }
 }
 ```
 
+**SQL-based MCP**
+```json label="cline_mcp_settings.json"
+{
+  "mcpServers": {
+    "token-api": {
+      "command": "npx",
+      "args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/sql"],
+      "env": {
+        "ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
+      }
+    }
+  }
+}
+```
+
+> [!NOTE]
+> The previous `--sse-url` option is deprecated, use `--remote-url`.
+
 ## Troubleshooting
 
 To enable logs for the MCP, use the `--verbose true` option.
 
+```json label="cline_mcp_settings.json"
+{
+  "mcpServers": {
+    "token-api": {
+      "command": "npx",
+      "args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/", "--verbose", "true"],
+      "env": {
+        "ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
+      }
+    }
+  }
+}
+```
+
 ### ENOENT
 
 ![Cline error dialog showing 'ENOENT' system alert.](/img/cline-error.png)

@@ -5,11 +5,15 @@ sidebarTitle: 'Introduction'
 
 Token API MCP server is an open-source implementation of [Anthropic's Model Context Protocol](https://modelcontextprotocol.io/introduction).
 
-This MCP server makes on-chain token data, including metadata, balances, transfers, and holder statistics, accessible through a set of MCP tools. Any compatible client can use these tools to fetch and analyze token information through a standardized interface. It connects to The Graph's hosted Token API database, enabling AI assistants to query real-time blockchain data using natural language requests that get translated into optimized SQL queries.
+This MCP server makes on-chain token data, including metadata, balances, transfers, and holder statistics, accessible through a set of MCP tools. Any compatible client can use these tools to fetch and analyze token information through a standardized interface. It connects to The Graph's hosted Token API database, enabling AI assistants to query blockchain data using natural language requests.
 
-The server itself does not host any language model. It simply converts MCP calls into data look-ups and returns structured results, letting the client's own LLM incorporate the results.
+There are two types of MCP available for use:
+- A REST-based MCP, the default, that communicates with the Token API.
+- A SQL-based MCP, for advanced users, that allows for communicating with the backend databases that powers the Token API.
 
-Think of it as a USB-C hub: it standardizes the plug-and-play connection between AI agents and The Graph's Token API data.
+The REST-based MCP simply exposes the API endpoints to your LLM based on the OpenAPI specification (available at https://token-api.thegraph.com/openapi). It is the *recommended way* to setup an LLM with Token API as the set of tools it offers is straightforward to use for any language model. Additionnaly, it automatically stays up-to-date with new Token API releases so you don't miss any new features !
+
+The SQL-based MCP provides the LLM tools to list databases and tables as well as run SQL queries directly on the data. It is meant for advanced users who need different use cases that the standard API endpoints cannot replicate. For best results, it is advised to use an LLM model specifically tuned for working with SQL as general purpose LLMs models (like Sonnet, Gemini, etc.) might not be able to generate valid queries efficiently.
 
 ## What You Can Do
 
@@ -20,4 +24,4 @@ Think of it as a USB-C hub: it standardizes the plug-and-play connection between
 - Ask natural language questions about token data without writing smart contract calls
 - Access historical transfer data to analyze token movement over time
 
-The Token MCP server provides [Claude](/ai-suite/token-api-mcp/claude/), [Cline](/ai-suite/token-api-mcp/cline/), and [Cursor](/ai-suite/token-api-mcp/cursor/) with direct, conversational access to onchain token data.
+The Token MCP server provides [Claude](/ai-suite/token-api-mcp/claude/), [Cline](/ai-suite/token-api-mcp/cline/), [Cursor](/ai-suite/token-api-mcp/cursor/) and any other client with MCP integration a direct, conversational access to onchain token data.
@@ -283,12 +283,26 @@ You can find the code for the MCP client in [The Graph's repo](https://github.co
 
 ### MCP integration with Claude/Cline/Cursor shows errors like "ENOENT" or "Server disconnected". How do I fix this?
 
-For "ENOENT" errors, ensure Node.js 18+ is installed and the path to `npx`/`bunx` is correct (consider using full paths in config). "Server disconnected" usually indicates authentication or connectivity issues – verify your `ACCESS_TOKEN` is set correctly and your network allows access to `https://token-api.mcp.thegraph.com/sse`.
+For "ENOENT" errors, ensure Node.js 18+ is installed and the path to `npx`/`bunx` is correct (consider using full paths in config). "Server disconnected" usually indicates authentication or connectivity issues – verify your `ACCESS_TOKEN` is set correctly and your network allows access to `https://token-api.mcp.thegraph.com/`.
 
 ### Do I need to use MCP or tools like Claude, Cline, or Cursor?
 
 No, these are optional. MCP is an advanced feature allowing AI assistants to interface with the API via streaming. For standard usage, simply call the REST endpoints with any HTTP client using your JWT. Claude Desktop, Cline bot, and Cursor IDE integrations are provided for convenience but aren't required.
 
+### How do I choose between the REST-MCP and the SQL-MCP and which one should I use ?
+
+To use one or the other, you need to supply the adequate URL in your configuration file (see the [docs](https://thegraph.com/docs/en/ai-suite/token-api-mcp/introduction/) for how to setup your configuration):
+- `https://token-api.mcp.thegraph.com/` is for the REST-MCP
+- `https://token-api.mcp.thegraph.com/sql` is for the SQL-MCP
+
+Which one you'll want to use depends on your use cases. Most of the time you should use the REST-MCP as it's the simplest way for the LLM to interact with blockchain data from the Token API. If you want answers to basic questions such as `What is the balance of ...`, `How many holders of ...`, etc. the REST-MCP gives your LLM all the tools it needs.
+
+The SQL-MCP should be used in an analyst use case where complex aggregations are needed that the Token API doesn't provide on its endpoints. It will require the LLM to discover and craft working SQL queries on the backend databases of the Token API.
+
+### Will using the REST-MCP counts towards my Token API usage ?
+
+Yes, you need to provide your Token API token to the MCP for authenticating with the Token API. The MCP makes API requests on your behalf when your LLM interacts with it.
+
 ## NFT Spam Detection
 
 ### What is NFT spam detection?