MCP Servers

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.

Looking for the agent workflow?

Start with Protocols for agents for wallet actions and execution, or Explore on-chain for data investigation. This page is the server and tool reference.

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)	Protocol actions and execution, cloud dev tools, registry discovery, knowledge, and live data

a4 init writes both servers, named arete (stream) and arete-docs (documentation), into the MCP config of the coding agent it runs in and any agent set up in the project folder (--agents <id> adds others). 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 replaces SDK generation (a4 install) or the generated Program SDK transaction surface. MCP supports agent investigation and protocol execution; use generated dependencies in shipped application code.

The protocol tool guide covers prepare, submit, intent tracking, receipts, and the optional local signer. Environment tools control fork state and target protocol calls at the project’s dev deployment with dev: true.

---

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 concise Arete CLI field guide 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
• https://docs.arete.run/openapi.json — OpenAPI 3.1 for the documentation HTTP API (search_docs, fetch_page)

---

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 the selected agents, 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. Lists and searches never need a key; when the registry requires it, the tools that read install descriptors, artifacts and schemas do (see Authentication).

Tool	Parameters	Purpose
explore_stacks	{ fields?, full? }	List stacks in the registry. The websocket_url in each entry is what connect takes. Brief by default.
explore_stack	{ stack, summary?, views?, full? }	One stack, from its pinned install descriptor. Returns a compact summary unless you ask for more.
explore_stack_schema	{ stack }	Entity and view schema: field paths, types, primary keys, and the view ids subscribe accepts.
explore_programs	{ fields?, full? }	List standalone Solana programs installable independent of any stack. Hashes omitted by default.
explore_program	{ program, operationId?, sections?, full? }	One program, from its pinned install descriptor. Returns a compact summary unless you ask for more.
resolve_artifact	{ kind, hash }	Fetch a content-addressed artifact. kind is program-spec, live-spec, or stack-manifest.
search_catalog	{ query?, concept?, category?, kind?, mode?, target?, limit?, cursor?, fields?, full? }	Search the active catalog by intent. Brief results, 10 per page, unless you ask for more.
get_catalog_entry	{ kind, slug, fields?, full? }	One active catalog entry. Compact unless you ask for more.
list_catalog_vocabulary	{ full? }	Concept and category slugs and names for search_catalog filters.
explore_protocols	{ query?, cursor?, limit? }	Callable protocol packages listed on Arete, with trust tier, attested executions, steps and install command.

List, search and vocabulary tools are brief by default. Pass full: true for every field the server sent, or fields (top-level keys or dotted paths) to choose your own:

• search_catalog keeps kind, slug, name, version, protocol, summary, modes, installName, programs, stacks, sdkTargets and delivery.status/delivery.health for each result, returns 10 results per page unless you pass limit, and adds a top-level hint string naming full, fields and, when there is another page, cursor. Two keys are derived from those fields: live on stacks (true: a hosted stream to subscribe to now, i.e. modes include subscribe; false: definition-only, which installs as an SDK and streams once you deploy it) and, only when the server sent no programs/stacks links, related, the other results on the page with the same protocol as kind:slug. A stack’s programs ([{slug, programId}]) and a program’s stacks ([{slug, live}]) link the two, and the page-level protocols lists every stack and program of each result’s protocol, with matched on a narrowed search (false on those the search did not match: judge a protocol live for the query by its matched stacks only). A page continued with cursor after the catalog changed carries catalogChanged: true and may skip or repeat entries. mode: "subscribe" returns only live stacks. full: true returns the server’s results without them. Without any filter it returns an overview: up to 5 programs and 5 stacks (or limit of each), with nextCursors.program and nextCursors.stack to page one kind with kind and cursor.
• search_knowledge keeps type, slug, name, protocol, summary and coverage for each result, returns 10 results unless you pass limit, and adds a hint; full: true adds score and coverage_via. There is no cursor, so when a page is full the hint says to raise limit.
• list_catalog_vocabulary and list_concepts keep each concept’s and category’s slug and name, plus a hint. full: true adds descriptions, synonyms and related slugs.
• explore_stacks keeps name, description, websocket_url, entities, visibility, serviceClass and websocket_auth.required. These keys and any fields you request, including every field inside websocket_auth and http_auth such as session_endpoint and jwks_url, are reported as snake_case whichever spelling the registry sends. fields accepts either spelling. full: true returns the registry’s own spelling, which may be websocketUrl and websocketAuth.
• explore_programs drops release and spec hashes.
• get_catalog_entry stays complete apart from identity hashes, release notes and programIds, and adds live to a stack; full: true returns the entry as sent.

The stack and program lists stay JSON arrays, so they carry no hint.

explore_protocols finds callable protocol packages hosted on Arete: protocols their publishers listed, which an agent installs (a4 install protocol) and executes with the protocol tools. They are not the curated knowledge protocols of search_knowledge and get_protocol, which describe on-chain protocols. Each item keeps the registry’s fields (slug, name, description, version, packageRef, deploymentId, steps with scope and access, attestedExecutions30d, trustTier, reviewHash when reviewed, attestationPubkey, publisher) and adds trust, either reviewed by Arete or unreviewed (nobody at Arete reviewed its code), and install, the exact install command. Reviewed protocols come first, then the most executed. Pages hold 20 items (limit 1 to 50); pass nextCursor back as cursor with the same query.

explore_stack and explore_program return a summary by default, cut from the full descriptor on the client:

• explore_stack { stack }: live (whether the stack has a hosted stream), entities with their subscribable view ids and their token-amount fields (amountFields, with scale and decimals), the read.* helpers the stack’s SDK extension adds (reads, e.g. read.currentRound()), the program SDKs the stack carries, stream endpoints, and stream auth: the accepted key classes, whether transactions need an entitlement, and the command for an origin-bound browser key when publishable keys are accepted. No identity hashes or SDK metadata.
• explore_stack { stack, views: ["OreRound/latest", "OreMiner/state"] }: only those views, each with its entity’s field schema (with descriptions and token-amount units) and primary key. Prefix alias: when several LiveSpecs select the same view id.
• explore_program { program }: identity, the names of the program’s accounts, instructions, events and types with the first line of each instruction’s and account’s docs (descriptions), the PDAs it derives with their seeds (pdas), its semantic SDK operations (for example transactions.mining.deployWithCheckpoint), and its Program Read and transaction transports.
• explore_program { program, operationId }: one operation, by semantic path, full operation id, generated binding or raw IDL instruction name (deploy). It returns the generated paths, input type, required and derived accounts, signers, transaction count, program errors, transport and scopes, and a minimal usage line. Anything the descriptor does not carry is listed under notReported rather than guessed.
• explore_program { program, sections }: accounts, events, instructions (with error codes), operations (every SDK surface entry) or types, in detail. Pass a list or a comma-separated string.
• full: true (or summary: false on explore_stack): the whole descriptor a4 install consumes, unchanged, with identity hashes (for resolve_artifact), every auth surface and endpoint, and SDK extension sources. This can run to hundreds of KB, so ask for it only when you need those.

A definition-only stack is not an error: explore_stack and explore_stack_schema return kind: "stack-definition-only", live: false, its catalog version, protocol and summary, and next steps: install its SDK with a4 install stack <slug> --ts, deploy it yourself with a4 up, or search for a live stack with mode: "subscribe".

get_catalog_entry is compact by default: identity hashes (packageReleaseHash, bundleHash, setHash, …), programIds and release notes are dropped from the entry. Pass fields (a list or a comma-separated string of top-level keys or dotted paths, e.g. "slug,kind,name,version,modes,delivery.health") to keep only those keys, or full: true for the entry exactly as the server sent it, for example to check that the lockfile records the same packageReleaseHash.

Semantic operations come from the knowledge layer’s SDK surface, which needs an API key. Without one, the summary says why operations are unavailable, and raw IDL instruction names still resolve through operationId.

Field descriptions. When a stack is published in the catalog, explore_stack_schema and the explore_stack views attach the curated field descriptions from its catalog knowledge. Fields carry a description, and entities and views carry a summary (in the explore_stack summary too). Descriptions carry usage guidance, such as which of two similar fields a live UI should show or when a field fills in, so read them before choosing fields. knowledge names the source document. Descriptions are attached only when the knowledge was published for the StackManifest the registry serves for that stack. No API key is needed, and a stack without a catalog entry returns its schema unchanged.

Token amounts. explore_stack_schema and explore_stack views attach amount to each field (the explore_stack summary lists them per entity as amountFields) the stack scales with ui_amount(decimals), read from the stack’s own computations: scale: "ui" is whole token units (the raw amount divided by 10^decimals, a float), scale: "raw" the integer base units it is computed from (often a string-encoded u64; for SOL, lamports). decimals (or decimalsFrom, the field holding them) and counterpart, the field with the same amount at the other scale, come with it. Check amount before converting or labelling a value.

{ "path": "state.total_deployed", "rust_type": "Option < f64 >", "amount": { "scale": "ui", "decimals": 9 } }

A summary, one operation or a few views is usually a few KB. Full bodies are the registry’s JSON, passed through unchanged. Any tool result over 512 KB is refused rather than truncated. Install descriptors are read up to 8 MB, so the summary, views and WebSocket URL of a stack with large programs still come back; only full: true is refused for such a stack, naming the arguments that return less. Past 8 MB, explore_stack_schema still lists the view ids and read_view accepts the stack’s WebSocket URL as url (websocket_url in explore_stacks).

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 (full: true; summaries, sections, views and operations are camelCase too)
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 (normally the agent profile written by a4 auth signup). Without one the call fails up front with an error pointing at signup/login; there is no public subset. The tool descriptions below are the ones the server publishes.

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

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.

Results are brief by default (10 of them unless you pass limit): each keeps type, slug, name, protocol, summary and coverage, and the response carries a top-level hint. Pass full: true for every field (score, coverage_via) or fields to choose keys.

AUTH: unlike the explore_* tools, this requires an Arete API key (normally the agent profile written by a4 auth signup).

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 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 { full? }

List the controlled vocabularies of the knowledge layer: concept slugs (actions/observables like swap or add-liquidity) 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. By default each item keeps only slug and name; pass full: true for descriptions, synonyms and related concepts.

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 Catalog and Descriptors.

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

Reading a view once

read_view answers “what is the current X” in one call: it connects, subscribes, waits for the snapshot, returns the entities and disconnects. Nothing it opens outlives the call. Pass stack (a bare reference like ore) or url, and the view id; credentials resolve as for connect.

Argument	Description
stack or url	Bare stack reference, or the stack’s WebSocket URL
view	<EntityName>/<view>, e.g. OreRound/latest
key	Read one entity (usually with an <EntityName>/state view)
where, filters	Same filters as query_entities, ANDed
select	Comma-separated dot paths to project
limit	Most entities, in the view’s order (default 10, max 1000)
timeout_secs	Seconds to wait for the connection and snapshot (default 15, max 60)

read_view({ stack: "ore", view: "OreRound/latest", limit: 1,
            select: "id.round_id,state.total_deployed,treasury.motherlode" })
→ { "view": "OreRound/latest", "total": 1, "matching": 1, "returned": 1, "truncated": false,
    "entities": [{ "id.round_id": "434165", "state.total_deployed": 4.93, "treasury.motherlode": 37.2 }] }

An unknown view, a key with no entity, or a snapshot that does not arrive in time is an error that says so.

read_view and the other stream tools return wire names (id.round_id). The generated TypeScript SDK’s rows use camelCase paths (id.roundId); look them up with describe_sdk before writing SDK code.

Installed SDK reference

describe_sdk returns the reference of an SDK installed in the project the server runs in (the nearest arete.toml at or above its working directory), from the files a4 install wrote, never from the registry. It is the same content as the SDK folder’s README.md and a4 sdk describe: the import and export, each entity’s views and row fields (TypeScript path next to the wire name, type, unit), the stack’s read.* helpers and its programs’ reads and operations.

Argument	Description
alias	Dependency alias from arete.toml; omit to list the installed SDKs
kind	stack or program, when the alias names both
view	Only one entity (OreRound) or view (OreRound/latest), with its fields
read	Only one read or program operation (currentRound, deploy)
program	Only one program (ore)
format	markdown (default) or json

An unknown alias, view or read is an invalid-params error that lists what is installed.

Dev environment tools

These tools act on an Arete cloud dev environment: the project’s (the nearest .arete/dev/environment.json at or above the server’s working directory, or project), ARETE_DEV_ENV, or the one environment names (a name or an id). They never start or stop processes; a4 dev up in a terminal creates or wakes the project’s environment and serves it locally. The account key goes only to https://api.arete.run, the ARETE_API_URL origin, or the API your a4 login is stored for: a project file naming any other API gets no key, and the tool fails before sending anything.

Tool	Arguments	What it does
dev_status	environment?, project?	the environment (state, tier, storage), whether a4 dev up serves it (upRunning), the session’s URLs and deployment, the chain’s slot and clock, and the stack stream URL with its token redacted
dev_environments		your environments and your plan’s quotas and usage
dev_wake, dev_sleep	environment?, project?	wake the environment, or put it to sleep now (its state is kept)
dev_delete	confirm, environment?, project?	delete it with its checkpoints; confirm must repeat its name
dev_checkpoint	action? (create, list, delete), checkpoint?, environment?, project?	save, list or delete checkpoints
dev_branch	checkpoint, name, environment?, project?	a new environment from a checkpoint
dev_restore	checkpoint, environment?, project?	restore a checkpoint (later writes are undone)
dev_rebase	keep?, environment?, project?	refetch every account the environment never wrote from mainnet; returns how many were reset and kept
dev_reset	confirm, environment?, project?	a fresh fork; confirm must repeat the environment’s name
dev_reset_account	account, include_owned?, environment?, project?	drop one account so its next read refetches it
dev_pin, dev_follow	account, include_owned? (pin), undo?, environment?, project?	pin an account (never refreshed) or follow one (refetched every block); undo reverses it
dev_fund	account, sol?, mint?, amount?, token_program?, environment?, project?	set a SOL balance (default 100), or a token balance with mint and amount; account is a public key or a dev wallet name
dev_warp	to (+2h, Unix seconds, slot:<n>, epoch:<n>), environment?, project?	move the clock forward; returns it before and after
dev_scenario	scenario (a document or a file path), dry_run?, environment?, project?	run an arete.scenario/v1 document; returns each step’s writes and expectations, passed and a digest
dev_preview	transaction (base64), environment?, project?	simulate without committing: compute units and every account before and after
dev_repro	signature, output?, environment?, project?	the minimal state to reproduce a sent transaction
dev_environment_events	after?, limit?, environment?, project?	the environment’s lifecycle events
dev_step	step, instance?, args?, wallet?, project?	prepares the step on the project’s dev deployment, signs locally with a dev wallet, submits and waits; returns state, executionId, instanceId
dev_instance	instance, wallet?, project?	reads one protocol instance; with wallet (a dev wallet name or a public key), allowedSteps is evaluated for it
dev_actions	wallet, instance?, cursor?, project?	what the wallet can do now: create steps and the instances it relates to, each step with allowed, reason, scope, args
dev_events	after?, limit?, waitMs?, types?, project?	the running a4 dev up’s event feed since a cursor: builds, deploys, steps, instance changes, stack rows, clock jumps and the environment’s lifecycle; returns cursor
dev_capture	programs, from, to?, output, rpc_url?, accounts?, max_transactions?	record a window of raw updates from a Solana RPC node into a .arcap capture

See Develop with a4 dev and cloud dev environments.

Protocol tools

Act on a protocol deployment from an agent: find what a wallet can do, prepare a step, sign it outside the server, submit it. They call Arete with the resolved API key (never a tool argument); dev: true uses the project’s deployment in its dev environment. Name the deployment with deployment or a protocol package reference protocol.

Tool	Arguments	What it does
protocol_actions	wallet, deployment? | protocol?, instance?, cursor?, dev?	create steps and the instances the wallet relates to, each step with its availability, scope and typed args
protocol_instances	deployment? | protocol?, state?, cursor?, dev?	one page of instances, newest first
protocol_instance	instance, wallet?, deployment?, dev?	one instance; allowedSteps for wallet
protocol_prepare	step, wallet, instance?, args?, deployment? | protocol?, transaction_format?, dev?	unsigned transactions and a summary to check before signing; rejections are results
protocol_submit	executionId, signedTransactions, wait?, timeoutSeconds?	submits the signed transactions and waits (bounded) for the intent to settle
protocol_intent	executionId	the execution intent’s state
protocol_receipt	signature	fetches the signed execution receipt and checks it offline and, with an RPC, against the transaction
protocol_execute	as protocol_prepare without wallet, wait?	only with a configured signer: prepares, checks the signer’s policy, signs, submits and waits

See Protocols for agents for the flow, the summary and the signer config.

protocol_check (arguments dir? or spec?) runs Arete’s own upload checks on a built protocol release without uploading it: the expression type checks, and the template checks against the pinned program specs. It reads <dir>/.arete/protocol/ (protocol-spec.json, plus handlers.mjs when a step has a handler) or takes an inline spec, and returns passed. A rejection lists errors, each with the spec path (a JSON pointer), code and message. It stores nothing and needs a secret key.

Account Squads tools

A production deployment of a protocol with Squads steps is refused (protocol-squads-setup-required) unless the multisig in its deployment config is an active attachment of the account. These tools read and set that up, and their answers guide the agent in this order: declare the multisig as a resource of the protocol; ask the user whether they already have a Squads multisig and how its members sign; send them to the dashboard (app.arete.run/dashboard/squads, any browser wallet including a Ledger) or the Squads app (Members → Add member → the proposer → Initiate only → approve and execute); put the active multisig’s address in the deployment config; for code, use the Arete setup helpers of the Squads v4 program SDK (a4 install program squads-v4). Arete builds no Squads transactions, and these tools never sign for a member.

Tool	Arguments	What it does
squads_status	multisig?	setup (notStarted, ready, needsAttention), the proposer, each attachment’s state, problem and dashboard link, and next
squads_attach	multisig, label?	attaches an existing multisig (active when the proposer is already a member, else pending) and returns the Squads-app steps

Squads onboarding tools (per deployment)

A step whose authority is squadsProposer is proposed to the team’s own Squads v4 multisig by a proposer key Arete holds for the account (one per account, shared by its deployments). The proposer may only initiate: add it to the multisig as a member with exactly the Initiate permission (mask 1) and fund it with a little SOL, since it pays the fee and rent of each proposal. The members still approve and execute. These tools only read.

Tool	Arguments	What it does
protocol_squads_proposer	deployment? | protocol?, dev?	the proposer’s pubkey, permissions (initiate) and its SOL balance when an RPC is configured
protocol_squads_status	multisig, deployment? | protocol?, dev?	ready, member, mask, threshold, problem (not_member, permissions_invalid, proposer_unfunded), balance and minimum, and next

Arete builds no Squads transactions. next points production teams at the dashboard or the Squads app, and dev environments at a4 dev squads add-proposer.

Streaming tools

Stateful, for following a view over time. A session calls connect once, then subscribe, then reads the cache. The cache reads wait up to 5 seconds for the subscription’s snapshot and report ready; ready: false means it has not arrived, usually because the view id is wrong.

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. The result includes a next hint with the get_recent call for the new subscription.
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	{ subscription_id, n? }: up to n entities (default 10, max 1000; limit is an alias) from the subscription’s exact ordered query membership. Example: { "subscription_id": "sub_1", "n": 10 }.
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 and field amounts
read_view({ stack: "ore", view })       → the current entities, once

# or, to follow updates:
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; it must match the selected built-in profile)
2. When ARETE_PROFILE is selected, that named profile of the a4 login
3. Without a selected profile, ARETE_API_KEY, then an unambiguous profile or legacy entry of the a4 login

account_status reports the resolved account: its plan, claim state and, when the account reports it, the plan’s usage. usage.onExhausted says what happens once the allowance is used: block (requests are refused) or metered (usage continues and is billed, with overage: "metered beyond allowance").

Generated MCP config runs a4 --profile agent mcp; the selected profile deliberately outranks an ambient human key. Run a4 --profile agent auth signup --if-missing during bootstrap and omit the argument. Humans store a separate key with a4 auth login --profile human --key <a4_sk_…>.

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. When the registry requires it, install descriptors, artifacts and stack schemas (explore_stack, explore_stack_schema, explore_program, explore_protocol, resolve_artifact) need a key too; without one the tool fails with code registry-key-required and says to run a4 login (free) or set ARETE_API_KEY in the server’s environment. 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": ["--profile", "agent", "mcp"] },
    "arete-docs": { "type": "http", "url": "https://docs.arete.run/mcp" }
  }
}

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

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

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

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

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

[mcp_servers.arete]
command = "a4"
args = ["--profile", "agent", "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", "--profile", "agent", "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": ["--profile", "agent", "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.