> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockgence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to the MCP

> Connect your AI assistant to Blockgence with a URL and your key, or with OAuth sign-in.

The Blockgence MCP server lets your AI assistant investigate on-chain from the chat: «is this wallet risky?», «follow
this hacker's money», «is this contract a honeypot?». It works with any client that speaks
[MCP](https://modelcontextprotocol.io) over HTTP: Claude Code, Claude Desktop, claude.ai, Cursor, Codex and others.

Every tool queries the API with **your** account: it sees your labels and uses your quota, just like the web app. The
server stores no key of its own.

## What you need

**1. The URL**

```
https://mcp.blockgence.com/mcp
```

**2. Your key**

At [app.blockgence.com](https://app.blockgence.com), your name's menu → **MCP…** → *Crear clave* (create key). It is
shown only once: copy it right then. You can have up to 5, one per client or machine, and revoke any of them
instantly. See [API keys](https://docs.blockgence.com/en/get-started/api-keys.md).

**3. Configure your client**

The key goes with every request, in the `Authorization: Bearer bkg_live_…` header. **MCP…** has a block ready to
paste into each client, with the URL and your key already filled in.

## Configuration per client

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http blockgence https://mcp.blockgence.com/mcp \
>   --header "Authorization: Bearer bkg_live_…"
> ```

> [tab] Cursor
>
> In `~/.cursor/mcp.json` (or Settings → MCP):
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "blockgence": {
>       "url": "https://mcp.blockgence.com/mcp",
>       "headers": { "Authorization": "Bearer bkg_live_…" }
>     }
>   }
> }
> ```

> [tab] Codex
>
> In `~/.codex/config.toml`:
>
> ```toml theme={null}
> [mcp_servers.blockgence]
> url = "https://mcp.blockgence.com/mcp"
> http_headers = { Authorization = "Bearer bkg_live_…" }
> ```

> [tab] Claude Desktop
>
> In `~/Library/Application Support/Claude/claude_desktop_config.json`. It uses
> [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), so you need Node:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "blockgence": {
>       "command": "npx",
>       "args": ["-y", "mcp-remote", "https://mcp.blockgence.com/mcp",
>                "--header", "Authorization:${BLOCKGENCE_AUTH}"],
>       "env": { "BLOCKGENCE_AUTH": "Bearer bkg_live_…" }
>     }
>   }
> }
> ```

Restart your client: the Blockgence tools show up. See the [list of tools](https://docs.blockgence.com/en/mcp/tools.md).

## claude.ai and other connectors with sign-in

With a client that supports OAuth, you do not paste any key. In claude.ai: **Settings → Connectors → Add custom
connector**, with the name «blockgence» and the URL `https://mcp.blockgence.com/mcp`.

**1. The client registers itself**

It discovers the Blockgence authorization server and registers without you doing anything.

**2. You sign in and approve**

It sends you to Blockgence: you sign in as usual (also with Google, if enabled) and approve. The screen says which
app is asking for access and **where the browser returns to**.

**3. Done**

The app gets a key of yours that expires daily and renews itself. It uses your account and your plan.

> [!WARNING]
>
> If you did not start that connection, reject it. Connected apps are listed and disconnected under **MCP… →
> Aplicaciones conectadas** (connected apps); disconnecting revokes the connection and all its keys instantly.

## If something fails

| What you see | What is happening | What to do |
| - | - | - |
| «Unauthorized» (`401`) when connecting | The key is missing or was revoked. | Create another one in **MCP…** and update the configuration. |
| `503` when connecting | The Blockgence API is not answering. It is retryable and does not mean the key is invalid. | Retry in a few minutes. |
| A tool returns `source_unavailable` | The data source failed to read what you asked for. You were not charged. | Retry if `retryable` is `true`; otherwise the query cannot be made with that network or source. |

Tools follow the same rules as the API for failures and cutoffs: a failure is never «no data», and a partial result
carries `degraded_sources`. See [Errors](https://docs.blockgence.com/en/api/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.