MCP Server

For AI agents: the documentation index is at llms.txt (full corpus: llms-full.txt). A markdown source for this page is /agent-skills/mcp.md.

Arete ships two MCP servers. They serve different purposes and can be run together.

Server	Transport	What it gives your agent
Documentation	HTTP (https://docs.arete.run/mcp)	Search and read these docs without scraping
Stream	stdio (a4 mcp)	Registry discovery, the curated knowledge layer, and live entity data, inside the agent loop

a4 init writes both servers, named arete (stream) and arete-docs (documentation), into the MCP config of every coding agent it detects. Run it once per project (or a4 init --global for your user) and skip the manual snippets below; a4 doctor reports drift as agents.<id>.mcp and a4 doctor --fix rewrites them.

a4 init -y
a4 doctor --json

Neither server covers SDK generation (a4 install) or transaction construction. Those are CLI and SDK operations.

---

Documentation server

The Arete documentation MCP server gives AI tools first-class access to the docs instead of requiring them to scrape pages.

Endpoint

Use the canonical HTTP endpoint:

https://docs.arete.run/mcp

The legacy alias https://docs.arete.run/mcp/sse is still available for older configurations.

Tools

Tool	Purpose
search_docs	Search the Arete docs and return ranked snippets with page slugs.
fetch_page	Fetch a documentation page as raw markdown by slug.

The server also exposes the Arete platform skill as a resource at https://docs.arete.run/skill.md.

Configure your agent

a4 init registers this server as arete-docs. To add it by hand, use the shapes under Configure your agent below, or for Claude Code:

claude mcp add --transport http arete-docs https://docs.arete.run/mcp
claude mcp list

Discovery

Discovery metadata is available at:

• https://docs.arete.run/.well-known/mcp
• https://docs.arete.run/.well-known/mcp.json
• https://docs.arete.run/.well-known/mcp/server-card.json

---

Stream server

The stream MCP server (a4 mcp) is a local stdio server that discovers registry resources, queries the curated knowledge layer, and opens WebSocket connections to deployed Arete stacks, caching streamed entities in memory. Use it when you want live data inside the agent loop — for exploration, debugging, or answering questions about current chain state. For application code, generate an SDK with a4 install instead.

Run

The server is built into the a4 binary; there is nothing separate to install:

a4 mcp

It speaks MCP over stdio and writes logs to stderr only. Install a4 with curl -fsSL https://arete.run/install.sh | sh (see Installation). a4 init writes the config for every detected agent, using the absolute binary path so GUI hosts that do not inherit your shell PATH still find it. The npm package @usearete/mcp is deprecated; replace npx -y @usearete/mcp with a4 mcp in any existing config.

Discovery tools

Read-only lookups against the public /api/registry/* endpoints. No signup required — public stacks and programs are visible to unauthenticated callers. When an api key resolves, explore_stacks also returns global stacks; a missing key is never an error here.

Tool	Purpose
explore_stacks	List stacks in the registry. The websocket_url in each entry is what connect takes.
explore_stack	Pinned install descriptor for one stack — the exact identities a4 install would consume.
explore_stack_schema	Entity and view schema: field paths, types, primary keys, and the view ids subscribe accepts.
explore_programs	List standalone Solana programs installable independent of any stack.
explore_program	Pinned install descriptor for one program: identity hashes, accounts, instructions, events, types.
resolve_artifact	Fetch a content-addressed artifact. kind is program-spec, live-spec, or stack-manifest.

Responses are the registry’s JSON, passed through unchanged. Bodies over 512 KB are refused rather than truncated — use a4 explore for payloads that large.

Key casing is not uniform across these tools

Read the keys you actually receive rather than assuming one convention:

Tool	Casing
explore_stacks, explore_stack_schema	snake_case — websocket_url, http_auth, stack_name, primary_keys, rust_type
explore_stack, explore_programs, explore_program	camelCase — websocketUrl, installName, programSpecHash, stackManifestHash
resolve_artifact	camelCase envelope (artifactHash, artifactVersion, kind, payload); the payload is the stored artifact and may be snake_case inside, e.g. an embedded IDL’s program_id and is_signer

Separately, a4 explore --json is camelCase throughout, so CLI field names do not transfer to explore_stacks or explore_stack_schema field-for-field.

Knowledge tools

Read-only lookups against /api/registry/knowledge/* — the curated, human-reviewed layer that maps an intent to protocols, programs, stacks, and recipes. Unlike the discovery tools, every knowledge tool requires an API key (ARETE_API_KEY, or the file a4 auth login writes). Without one the call fails up front with an error pointing at a4 auth login; there is no public subset. The tool descriptions below are the ones the server publishes.

search_knowledge { query?, concept?, category?, limit? }

Search the curated Solana knowledge layer for protocols, programs, stacks, and recipes that serve an intent. Start here when you need to find which protocols/programs/stacks serve an intent like ‘monitor swaps’ or ‘execute through a multisig’.

query is free text, matched against concept names and synonyms first, then protocols/programs/recipes via full-text search. concept and category filter by exact slug — discover slugs with list_concepts. At least one of the three is required.

Each result carries coverage flags: read (fetch on-chain account state), build (construct transactions), subscribe (stream live entities from a hosted stack) — pick the mode you need, then drill in with get_protocol, get_program_knowledge, or get_recipe.

AUTH: unlike the explore_* tools, this requires an Arete API key (ARETE_API_KEY env var, or the file a4 auth login writes).

get_protocol { protocol }

Fetch curated knowledge for one protocol by slug (e.g. meteora-damm): description, categories, links, its on-chain programs with roles (core/periphery/deprecated), related protocols (composes-with, wraps, graduates-to, …), the public stacks streaming its entities, and per-concept coverage (read/build/subscribe).

Use after search_knowledge to decide how to integrate a protocol; follow programs[].slug into get_program_knowledge for instruction-level detail.

Pass a bare slug, not a URL. Requires an API key (a4 auth login).

get_program_knowledge { program, section? }

Fetch curated, human-reviewed annotations for one Solana program by slug (e.g. meteora-cp-amm). section selects what comes back:

• summary (default) — program header, provenance, and counts
• instructions — per-instruction semantics: what each instruction does, argument and account meanings, concepts
• accounts — account-type semantics and field meanings
• surface — the ingested SDK extension surface for this program (callable operations with bindings)

Sections keep responses under the 512 KiB tool-result cap — fetch only the section you need. Pass a bare slug, not a URL. Requires an API key (a4 auth login).

get_recipe { recipe }

Fetch one cross-protocol recipe by slug (e.g. execute-presale-purchase-via-squads): an ordered, curated sequence of steps for a multi-protocol pattern (e.g. wrap a prepared transaction in a Squads multisig), each step referencing a real SDK surface entry (resolved in the response), plus a path to working example code.

Use when search_knowledge returns a recipe result or a protocol’s related edges cite one as evidence.

Pass a bare slug, not a URL. Requires an API key (a4 auth login).

list_concepts {}

List the controlled vocabularies of the knowledge layer: concept slugs (actions/observables like swap or add-liquidity, with synonyms and related concepts) and category slugs (protocol classifications like dex or launchpad).

Call this first when you want to filter search_knowledge by concept/category, or to map a user’s phrasing onto a canonical concept slug.

Requires an API key (a4 auth login).

The surface section of get_program_knowledge is how an agent learns which typed SDK operations exist for a program, with per-language bindings. Read it instead of reading SDK source for method names. The recipe catalog is growing; a missing recipe or protocol means “not yet documented”, not “unsupported”.

The CLI mirror is a4 know search|protocol|program|recipe|concepts [--json] — see Explore Stacks.

Walkthrough: “monitor swaps”

search_knowledge({ query: "monitor swaps" })
  → matched_concepts: ["swap"], results with coverage {read, build, subscribe}

get_protocol({ protocol: "<slug from results>" })
  → programs[], related[], stacks[{stack, entities}], coverage[]

# subscribe is set → stream it
explore_stack_schema({ stack })                     → exact view id
connect({ url }) → subscribe({ connection_id, view }) → query_entities(…)

# read / build only → generate an SDK and call the surface
get_program_knowledge({ program: "<programs[].slug>", section: "surface" })
  → callable operations with bindings; then `a4 install …` from the CLI

Streaming tools

Stateful. A session calls connect once, then subscribe, then reads the cache.

Tool	Purpose
ping	Health check. Returns pong.
connect	Open a WebSocket connection to a stack. Returns a connection_id.
disconnect	Close a connection and drop every subscription bound to it.
subscribe	Bind a view on a connection. Streamed entities land in an in-memory cache.
unsubscribe	Cancel a subscription by id.
query_entities	Filter and project cached entities. Accepts a string where DSL and structured filters (both ANDed).
get_entity	Fetch a single cached entity by key.
list_entities	List cached entity keys. Capped at 1000 per response; total_cached reports the true size.
get_recent	Return up to N entities from the subscription’s exact ordered query membership.
list_subscriptions	List active subscriptions, optionally filtered by connection_id.
list_connections	List all open connections.

View ids follow the <EntityName>/<view> template — e.g. OreRound/list, OreRound/latest. Call explore_stack_schema to get the exact ids rather than guessing from the template.

Typical session

explore_stacks()                        → pick a stack, note its websocket_url
explore_stack_schema({ stack: "ore" })  → get the exact view id
connect({ url })                        → connection_id
subscribe({ connection_id, view })      → subscription_id
query_entities({ subscription_id, … })  → data

Authentication

Do not pass api_key in tool calls. The server resolves credentials in this order:

1. Explicit api_key argument on connect (override — avoid in agent calls)
2. ARETE_API_KEY environment variable
3. The credentials file written by a4 auth signup or a4 auth login

Run a4 auth signup (or a4 auth login --key <a4_ak_…>) once and omit the argument.

The knowledge tools (search_knowledge, get_protocol, get_program_knowledge, get_recipe, list_concepts) require a key from step 2 or 3 and fail with an actionable error when none resolves. The discovery tools attach a resolved key only when ARETE_API_URL names an Arete origin over HTTPS — https://arete.run or any https://*.arete.run subdomain. Plain HTTP is accepted only for loopback (localhost, 127.0.0.1, [::1]), where the request never reaches a network. Everything else, including http://api.arete.run, gets an unauthenticated request rather than your key in cleartext or sent to a host it does not belong to — the endpoints these tools touch are public, so you still get the public result set.

Configure your agent

These are the files and shapes a4 init writes (project scope; --global uses the user-level file named in parentheses). Each includes both servers. Replace "a4" with the absolute path printed as A4_BIN= by the installer if your host does not inherit your shell PATH.

Claude Code — .mcp.json (~/.claude.json)

{
  "mcpServers": {
    "arete": { "type": "stdio", "command": "a4", "args": ["mcp"] },
    "arete-docs": { "type": "http", "url": "https://docs.arete.run/mcp" }
  }
}

Cursor — .cursor/mcp.json (~/.cursor/mcp.json)

{
  "mcpServers": {
    "arete": { "command": "a4", "args": ["mcp"] },
    "arete-docs": { "url": "https://docs.arete.run/mcp" }
  }
}

VS Code — .vscode/mcp.json (project only)

{
  "servers": {
    "arete": { "type": "stdio", "command": "a4", "args": ["mcp"] },
    "arete-docs": { "type": "http", "url": "https://docs.arete.run/mcp" }
  }
}

Codex — .codex/config.toml (~/.codex/config.toml)

[mcp_servers.arete]
command = "a4"
args = ["mcp"]

[mcp_servers.arete-docs]
url = "https://docs.arete.run/mcp"

Codex only loads the project file for trusted projects; a4 doctor reports an untrusted project as agents.codex-trust.

OpenCode — opencode.json (~/.config/opencode/opencode.json)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "arete": { "type": "local", "command": ["a4", "mcp"], "enabled": true },
    "arete-docs": { "type": "remote", "url": "https://docs.arete.run/mcp", "enabled": true }
  }
}

Gemini CLI — .gemini/settings.json (~/.gemini/settings.json)

{
  "mcpServers": {
    "arete": { "command": "a4", "args": ["mcp"] },
    "arete-docs": { "httpUrl": "https://docs.arete.run/mcp" }
  }
}

a4 init also supports Copilot CLI, Windsurf, Cline, Zed, Amp, Kiro, Roo, and Goose; run a4 init --agents <id> and inspect the reported path, or see the CLI reference for the full table.