@secondlayer/mcp
Gives your coding agent direct access to Stacks data, on the hosted API
(api.secondlayer.tools) or on your own instance:
Index (decoded rows), Subgraphs (tables you define, served from your account or instance),
and Streams (raw inputs). Exposes the golden-path tools only: Index reads, the
subgraph lifecycle, webhooks, contract discovery/scaffolding, instance
status, archive verify/bootstrap, and hosted credits/quote. Everything else
(single-record lookups, mempool, PoX, proofs, live Streams reads) is
available over REST /v1 + OpenAPI. There is no consume tool.
Hosted
No install: the hosted API serves the read tools over Streamable HTTP, with a
browser sign-in.
claude mcp add --transport http secondlayer https://api.secondlayer.tools/mcp
Clients without OAuth send Authorization: Bearer <sk-sl_ key>. Subgraph
deploys, webhooks, archive, codegen and instance tools are local only. See
/docs/mcp.
Install
Auth
Most reads are public: index_* and contracts_find work with no key. Subgraph tools need an INSTANCE_TOKEN past loopback, and so does GET /v1/subgraphs/<name>/<table> over HTTP ({ rows, next_cursor, tip } cursor envelope); on loopback it is open. There is no per-subgraph public or private flag. streams_dumps needs no key: the dumps manifest is public; the tool only needs SL_STREAMS_DUMPS_URL configured. streams_tip is key-mandatory (keyless → 401). Live Streams list reads are REST-only (GET /v1/streams/*). Writes (deploy, reindex, delete, webhooks) need a key, and the key follows the host: on https://api.secondlayer.tools the server uses SECONDLAYER_API_KEY (sk-sl_*) automatically; anywhere else it uses INSTANCE_TOKEN from secondlayer init. Hosted credits/quote use SECONDLAYER_API_KEY too. On the hosted API, subgraph sources are limited to event filters and contract_call/contract_deploy (422 SOURCE_NOT_HOSTABLE otherwise); set startBlock. Read secondlayer://context first: it reports auth state and read-auth tiers.
Quick Start — Stdio (IDE)
Add to your Claude Desktop or Cursor config:
{
"mcpServers": {
"secondlayer": {
"command": "bunx",
"args": ["-p", "@secondlayer/mcp", "secondlayer-mcp"],
"env": {
"SECONDLAYER_API_URL": "http://127.0.0.1:3800",
"INSTANCE_TOKEN": "..."
}
}
}
}
Quick Start — HTTP (Remote)
export SECONDLAYER_API_URL=http://127.0.0.1:3800
export INSTANCE_TOKEN=<from secondlayer init>
export SECONDLAYER_MCP_SECRET=your-secret
bunx -p @secondlayer/mcp secondlayer-mcp-http
Environment Variables
| Variable | Required | Default | Description |
|---|
INSTANCE_TOKEN | Writes on your instance | — | From secondlayer init. Required for write tools elsewhere than api.secondlayer.tools; reads are public. Not sent to the hosted API. |
SECONDLAYER_API_KEY | Hosted API, credits/quote/latest | — | sk-sl_*, used automatically when SECONDLAYER_API_URL is https://api.secondlayer.tools. |
SECONDLAYER_API_URL | No | http://127.0.0.1:3800 | Instance API, or https://api.secondlayer.tools for hosted. |
SECONDLAYER_BIN | CLI tools | secondlayer on PATH | Path to the CLI binary (bootstrap, repair). |
SECONDLAYER_CWD | CLI tools | process cwd | Compose project directory. |
SECONDLAYER_MCP_PORT | No | 3100 | HTTP transport port. |
SECONDLAYER_MCP_SECRET | No | — | Bearer token for HTTP auth. Disabled if unset. |
| Domain | Tools |
|---|
| Index (9) | index_events, index_ft_transfers, index_nft_transfers, index_contract_calls, index_blocks, index_transactions, index_print_schema, index_discover, batch_query |
| Subgraphs (12) | subgraphs_list, subgraphs_status, subgraphs_spec, subgraphs_scaffold, subgraphs_deploy, subgraphs_delete, subgraphs_query, subgraphs_backfill, subgraphs_reindex, subgraphs_stop, subgraphs_operations, subgraphs_gaps |
| Webhooks (13) | webhooks_create, webhooks_list, webhooks_get, webhooks_update, webhooks_delete, webhooks_test, webhooks_pause, webhooks_resume, webhooks_rotate_secret, webhooks_deliveries, webhooks_dead, webhooks_requeue, webhooks_replay |
| Streams (2) | streams_tip, streams_dumps |
| Contracts (2) | contracts_find, contracts_get_abi |
| Instance (1) | instance_status |
| Archive (5) | archive_verify, archive_bootstrap, archive_repair, archive_latest, archive_quote |
| Credits (1) | credits_balance (needs SECONDLAYER_API_KEY) |
| Account (4) | account_whoami, account_create_key, account_list_keys, account_rotate_key (only when pointed at https://api.secondlayer.tools) |
Verify after mutating: subgraphs_operations for deploy/reindex/backfill/stop,
webhooks_deliveries for create/test/replay. Empty index:
archive_bootstrap, poll instance_status until decoders are ok, then
archive_verify, then codegen_index_schema.
Periphery surfaces (single block/tx lookups, mempool, PoX, proofs,
credits/caps, live Streams reads/SSE) are REST-only: see the OpenAPI spec at
the API host. Live Streams list reads use GET /v1/streams/events.
Point the server at your instance with SECONDLAYER_API_URL (default
http://127.0.0.1:3800). Writes use INSTANCE_TOKEN from
secondlayer init. account_* tools appear only when the server is pointed at
https://api.secondlayer.tools.
webhooks_create triggers
Webhooks fire on raw chain events. Pass a triggers array (contract / event /
function / trait), e.g. [{ "type": "contract_call", "contractId": "SP....amm", "functionName": "swap-*" }]. To react to subgraph rows, read the
table from your own Postgres or poll the subgraph API.
subgraphs_query enhancements
fields — comma-separated column projection (e.g. "sender,amount_x")
count — boolean, returns row count instead of rows
- Filter operators:
eq, neq, gt, gte, lt, lte, like
- Max limit: 200
Resources
| URI | Description |
|---|
secondlayer://context | Live state — what exists (your subgraphs, webhooks, account), what you can do, and read-auth tiers. Read first. |
secondlayer://filters | Subgraph source filter types and their fields |
secondlayer://column-types | Column type mappings and options |
secondlayer://traits | SIP trait standards (valid trait values) |
secondlayer://chain-triggers | Chain-webhook trigger types and fields |
Error Handling
All tools return structured errors with isError: true:
{ "error": { "type": "not_found", "status": 404, "message": "Subgraph not found" } }
| Error type | Status | When |
|---|
unauthorized | 401 | Invalid or missing API key |
not_found | 404 | Resource doesn't exist |
rate_limited | 429 | Too many requests |
server_error | 5xx | Server-side failure |
error | other | Validation, bundling, etc. |
Bundle/deploy errors use descriptive prefixes: "Bundle failed:", "Module evaluation failed:", "Validation failed:". HTTP transport enforces a 1MB body limit (413) and JSON parse safety (400). Scaffold ABI fetch has a 10s timeout.
Programmatic Usage
import { createServer } from "@secondlayer/mcp";
const server = createServer();
License
MIT