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 <sk-sl_ key>. 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/<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
# Listening on port 3100

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.

Tools

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 (2)	account_whoami, account_create_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, 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

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

License

MIT