Skip to content

Commit 7db31d3

Browse files
0237hbenface
0237h
and
benface
authored
Update Token API MCP documentation (#1051)
* Update introduction.mdx - Adds the two types of MCP - Misc editing * Update claude.mdx - Adds REST MCP config - Updates config commands - Adds depreciation notice for `--sse-url` option - Improves troubleshooting section * Update faq.mdx - Adds `How do I choose between the REST-MCP and the SQL-MCP and which one should I use ?` - Adds `Will using the REST-MCP counts towards my Token API usage ?` * Update introduction.mdx Emphasizes REST easier to use for LLMs than SQL * Update cline.mdx Adds new instructions * Update cursor.mdx Adds new instructions * Update website/src/pages/en/token-api/faq.mdx Co-authored-by: Benoît Rouleau <benoit.rouleau@icloud.com> * Update website/src/pages/en/ai-suite/token-api-mcp/claude.mdx Co-authored-by: Benoît Rouleau <benoit.rouleau@icloud.com> * Update website/src/pages/en/ai-suite/token-api-mcp/introduction.mdx Co-authored-by: Benoît Rouleau <benoit.rouleau@icloud.com> * Update website/src/pages/en/ai-suite/token-api-mcp/introduction.mdx Co-authored-by: Benoît Rouleau <benoit.rouleau@icloud.com> * Update website/src/pages/en/token-api/faq.mdx Co-authored-by: Benoît Rouleau <benoit.rouleau@icloud.com> * Update website/src/pages/en/token-api/faq.mdx Co-authored-by: Benoît Rouleau <benoit.rouleau@icloud.com> * Fix lint --------- Co-authored-by: Benoît Rouleau <benoit.rouleau@icloud.com>
1 parent fa506ae commit 7db31d3

5 files changed

Lines changed: 135 additions & 13 deletions

File tree

‎website/src/pages/en/ai-suite/token-api-mcp/claude.mdx‎

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,30 @@ Create or edit your `claude_desktop_config.json` file.
1818
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
1919
- Linux: `.config/Claude/claude_desktop_config.json`
2020

21+
**REST-based MCP**
22+
23+
```json label="claude_desktop_config.json"
24+
{
25+
"mcpServers": {
26+
"token-api": {
27+
"command": "npx",
28+
"args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/"],
29+
"env": {
30+
"ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
31+
}
32+
}
33+
}
34+
}
35+
```
36+
37+
**SQL-based MCP**
38+
2139
```json label="claude_desktop_config.json"
2240
{
2341
"mcpServers": {
2442
"token-api": {
2543
"command": "npx",
26-
"args": ["@pinax/mcp", "--sse-url", "https://token-api.mcp.thegraph.com/sse"],
44+
"args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/sql"],
2745
"env": {
2846
"ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
2947
}
@@ -32,9 +50,27 @@ Create or edit your `claude_desktop_config.json` file.
3250
}
3351
```
3452

53+
> [!NOTE] The previous `--sse-url` option is deprecated, use `--remote-url`.
54+
3555
## Troubleshooting
3656

37-
To enable logs for the MCP, add the option `"--verbose", "true"` under `"args"`.
57+
To enable logs for troubleshooting the MCP, add the option `"--verbose", "true"` under `"args"`.
58+
59+
```json label="claude_desktop_config.json"
60+
{
61+
"mcpServers": {
62+
"token-api": {
63+
"command": "npx",
64+
"args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/", "--verbose", "true"],
65+
"env": {
66+
"ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
67+
}
68+
}
69+
}
70+
}
71+
```
72+
73+
Logs are available under `logs/mcp.log` and `logs/mcp-server-token-api.log` inside the folder of your Claude configuration file.
3874

3975
### ENOENT
4076

‎website/src/pages/en/ai-suite/token-api-mcp/cline.mdx‎

Lines changed: 37 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,24 +18,58 @@ Create or edit your `cline_mcp_settings.json` file.
1818

1919
> **MCP Servers** > **Installed** > **Configure MCP Servers**
2020
21+
**REST-based MCP**
22+
23+
```json label="cline_mcp_settings.json"
24+
{
25+
"mcpServers": {
26+
"token-api": {
27+
"command": "npx",
28+
"args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/"],
29+
"env": {
30+
"ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
31+
}
32+
}
33+
}
34+
}
35+
```
36+
37+
**SQL-based MCP**
38+
2139
```json label="cline_mcp_settings.json"
2240
{
2341
"mcpServers": {
24-
"mcp-pinax": {
42+
"token-api": {
2543
"command": "npx",
26-
"args": ["@pinax/mcp", "--sse-url", "https://token-api.mcp.thegraph.com/sse"],
44+
"args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/sql"],
2745
"env": {
28-
"ACCESS_TOKEN": "<JWT Token from thegraph.market>"
46+
"ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
2947
}
3048
}
3149
}
3250
}
3351
```
3452

53+
> [!NOTE] The previous `--sse-url` option is deprecated, use `--remote-url`.
54+
3555
## Troubleshooting
3656

3757
To enable logs for the MCP, use the `--verbose true` option.
3858

59+
```json label="cline_mcp_settings.json"
60+
{
61+
"mcpServers": {
62+
"token-api": {
63+
"command": "npx",
64+
"args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/", "--verbose", "true"],
65+
"env": {
66+
"ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
67+
}
68+
}
69+
}
70+
}
71+
```
72+
3973
### ENOENT
4074

4175
![Cline error dialog showing 'ENOENT' system alert.](/img/cline-error.png)

‎website/src/pages/en/ai-suite/token-api-mcp/cursor.mdx‎

Lines changed: 35 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,32 @@ Create or edit your `~/.cursor/mcp.json` file.
1818

1919
> **Cursor Settings** > **MCP** > **Add new global MCP Server**
2020
21+
**REST-based MCP**
22+
23+
```json label="mcp.json"
24+
{
25+
"mcpServers": {
26+
"token-api": {
27+
"command": "npx",
28+
"args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/"],
29+
"env": {
30+
"ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
31+
}
32+
}
33+
}
34+
}
35+
```
36+
37+
**SQL-based MCP**
38+
2139
```json label="mcp.json"
2240
{
2341
"mcpServers": {
24-
"mcp-pinax": {
42+
"token-api": {
2543
"command": "npx",
26-
"args": ["@pinax/mcp", "--sse-url", "https://token-api.mcp.thegraph.com/sse"],
44+
"args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/sql"],
2745
"env": {
28-
"ACCESS_TOKEN": "<JWT Token from thegraph.market>"
46+
"ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
2947
}
3048
}
3149
}
@@ -38,6 +56,20 @@ Create or edit your `~/.cursor/mcp.json` file.
3856

3957
To enable logs for the MCP, use the `--verbose true` option.
4058

59+
```json label="mcp.json"
60+
{
61+
"mcpServers": {
62+
"token-api": {
63+
"command": "npx",
64+
"args": ["@pinax/mcp", "--remote-url", "https://token-api.mcp.thegraph.com/", "--verbose", "true"],
65+
"env": {
66+
"ACCESS_TOKEN": "<https://thegraph.market JWT Access Token>"
67+
}
68+
}
69+
}
70+
}
71+
```
72+
4173
### ENOENT
4274

4375
Try to use the full path of the command instead:

‎website/src/pages/en/ai-suite/token-api-mcp/introduction.mdx‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,16 @@ sidebarTitle: 'Introduction'
55

66
Token API MCP server is an open-source implementation of [Anthropic's Model Context Protocol](https://modelcontextprotocol.io/introduction).
77

8-
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.
8+
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.
99

10-
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.
10+
There are two types of MCP available for use:
1111

12-
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.
12+
- A REST-based MCP, the default, that communicates with the Token API.
13+
- A SQL-based MCP, for advanced users, that allows for communicating with the backend databases that power the Token API.
14+
15+
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 set up 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!
16+
17+
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.
1318

1419
## What You Can Do
1520

@@ -20,4 +25,4 @@ Think of it as a USB-C hub: it standardizes the plug-and-play connection between
2025
- Ask natural language questions about token data without writing smart contract calls
2126
- Access historical transfer data to analyze token movement over time
2227

23-
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.
28+
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.

‎website/src/pages/en/token-api/faq.mdx‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -283,12 +283,27 @@ You can find the code for the MCP client in [The Graph's repo](https://github.co
283283

284284
### MCP integration with Claude/Cline/Cursor shows errors like "ENOENT" or "Server disconnected". How do I fix this?
285285

286-
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`.
286+
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/`.
287287

288288
### Do I need to use MCP or tools like Claude, Cline, or Cursor?
289289

290290
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.
291291

292+
### How do I choose between the REST-MCP and the SQL-MCP and which one should I use?
293+
294+
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 set up your configuration):
295+
296+
- `https://token-api.mcp.thegraph.com/` is for the REST-MCP
297+
- `https://token-api.mcp.thegraph.com/sql` is for the SQL-MCP
298+
299+
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.
300+
301+
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.
302+
303+
### Will using the REST-MCP counts towards my Token API usage?
304+
305+
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.
306+
292307
## NFT Spam Detection
293308

294309
### What is NFT spam detection?

0 commit comments

Comments
 (0)