Explore On-chain with MCP

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

This is the quickest way to find out what is happening on-chain. You ask a question in plain language. Your agent searches Arete for programs and live data that can answer it, checks the exact shape of that data, connects, and comes back with an answer and its sources. You don’t write any code.

The link between your agent and Arete runs over MCP (Model Context Protocol), the standard way agents plug into outside tools. a4 init sets it up for you.

Set up once

If you already followed the Quickstart, skip ahead to Ask a question. Otherwise, install the CLI and initialize the current project:

curl -fsSL https://arete.run/install.sh | sh
a4 init -y
a4 doctor --json

a4 init installs the Arete skills and connects two MCP servers to the agents it detects:

• arete searches the catalog, looks up curated knowledge, opens live connections, subscribes to views, and answers queries from a small local cache;
• arete-docs searches the current documentation.

If you use a desktop agent app and the new tools don’t show up on their own, restart it after initialization.

Knowledge queries and hosted connections may ask you to sign in:

a4 auth signup

Already have a key that a person issued to you? Use a4 auth login --key <key> instead. Either way, credentials stay in the CLI’s credential store. Never paste a secret key into a prompt or an MCP tool argument.

Ask a question

Agent prompt Copy / paste

Use Arete to find programs and currently deployed live views relevant to token activity. Inspect the exact schemas before connecting. Subscribe only long enough to gather a bounded sample, summarize what the data supports, name the programs and views used, and disconnect when finished. If no suitable hosted view exists, explain the gap instead of guessing.

A good prompt tells the agent:

• what you want to find out, in business or research terms;
• any protocols, assets, addresses, or time range you care about;
• whether you need a snapshot of right now or updates as they happen; and
• what form the answer should take.

You can leave out MCP tool names, program account names, and endpoints. The installed skills teach the agent to look those up from current metadata.

What the agent does

Here is what happens after you send that prompt. You don’t have to manage any of it, but knowing the steps makes it easier to judge the answer you get back.

1. Search by intent

The agent starts from your words and searches the catalog or the knowledge layer. It doesn’t guess a stack name. It looks for results that support the modes the task needs:

• subscribe for deployed live views;
• read for typed program accounts or chain state; and
• build when the task will eventually include a transaction.

2. Inspect exact descriptors

A search hit isn’t enough to connect or write code. The agent opens the descriptor for the program or stack (its exact spec sheet) and reads the real account names, available views, keys, fields, connection details, and sign-in requirements.

3. Connect to a suitable view

If a stack is subscribe-ready, the agent connects once, using the URL given in the descriptor, and subscribes to the smallest view and query window that will answer the question. It never builds a URL from a package name.

4. Query bounded state

While a subscription is active, the local MCP server applies incoming updates and keeps a small, bounded cache. The agent can fetch one entity, list entities, review recent updates, or filter the cached data to answer you.

Keep in mind that this cache is no substitute for a history database. What it holds depends on the view you chose, its query window, and how long the connection has been open.

5. Explain provenance and limits

A good answer tells you which program, stack, and view it came from, and separates what the agent observed directly from what it inferred. When the available view can’t support the conclusion you asked for, the agent should say so.

6. Disconnect

Exploration should have an end. The agent disconnects once it has answered, unless you explicitly asked it to keep monitoring.

From exploration to application code

Found a view worth building on? Install the exact stack it belongs to:

a4 explore catalog stack <slug> --json
a4 install stack <slug> --ts

This records the dependency and generates typed code for the view. Your app now works from the same contract your agent just explored through MCP.

Sometimes the catalog has the right program but no view with the data you need. In that case, write the missing piece down precisely: the programs, entities, primary keys, field sources, update routes, and query windows it would involve. That specification feeds the advanced Rust authoring workflow. Once the new view is deployed, come back to MCP and check it before installing its final stack SDK.

MCP is not the production SDK

MCP is for investigating, debugging, and helping your agent reason. Code that ships should use the generated SDKs:

Need	Use
Ask an ad hoc question	MCP
Inspect a live view during development	a4 get, MCP read_view, or a4 stream
Read program accounts in an application	Generated Program SDK
Maintain a live application subscription	Generated stack SDK
Build or execute transactions	Generated Program SDK and wallet adapter

The MCP server doesn’t replace SDK generation, and it never deploys custom infrastructure behind your back.

Troubleshooting

What you see	What to check
Your agent has no Arete tools	Run a4 doctor --json, apply its fix, and restart the agent
Search finds no hosted view	Broaden the query and check for subscribe coverage. Don’t let the agent invent a stack
The connection asks for a sign-in	Run a4 auth signup, or log in with the key you meant to use
A subscription returns no data	Check the view’s keys, filters, and snapshot behavior, and whether any matching activity occurred
The answer needs historical data	Confirm the view you chose keeps that history. The MCP cache alone is not historical storage

For exact tool contracts and manual configuration, see MCP Servers.