secondlayer

@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, stacking, 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 . Subgraph deploys, webhooks, archive, codegen and instance tools are local only. See /docs/mcp.

Install

bun add @secondlayer/mcp

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/ / 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= export SECONDLAYER_MCP_SECRET=your-secret bunx -p @secondlayer/mcp secondlayer-mcp-http

Listening on port 3100

Environment Variables

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, stacking, 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

Error Handling

All tools return structured errors with isError: true:

{ "error": { "type": "not_found", "status": 404, "message": "Subgraph not found" } }

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(); // Connect to your own transport

License

MIT