Spirit Room / Guides

How to onboard AI agents through your MCP server: no skills, no plugins, just the server

A user connects your MCP server, asks a normal question, and the agent asks “which platform?”. It's connected. It's authorised. It just doesn't know what your product is for. Most “agent onboarding” advice stops at OAuth. This guide is about what comes after: the agent's first five minutes.

Leonid Bugaev · Published 21 Oct 2026

What agent onboarding means

Search for “agent onboarding” and you'll mostly find auth: OAuth flows, dynamic client registration, API keys an agent can mint for itself. That part matters, and good guides exist for it. But a human user who has just logged in still gets an onboarding: a tour, an empty state that says what to do first, a help link. An agent gets none of that unless your server provides it.

So in this guide, onboarding means the agent's first five minutes after it connects:

• Recognition: does it know your product is the right tool for the user's question?
• First step: does it know where to start, and does it read your playbook before acting?
• House rules: does it know what must never happen, such as spending without asking or adding up numbers that shouldn't be added?
• Vocabulary: does it know that what the user calls a “task” your API calls an “item”?

How onboarding fails today

We ran a live, read-only trial on a 99-tool production MCP server: 3 everyday jobs in Claude Code and Codex, with and without the product's own agent skills installed, 2 runs each. Without skills, 2 of the 12 runs failed, both in Codex:

• In one, Codex didn't realise the question was about the product. It asked the user “which platform?” and made 0 calls to a server that was connected and working.
• In another, during a “just look” job, it reached for a paid research tool to open web pages. The read-only guard blocked it, and the run ended without an answer.

The runs that passed also skipped steps the product team cared about: one agent never checked the credit balance before planning a spend; another paged through every record instead of using the tool built for “what's new since yesterday”. Two runs per cell shows direction, not a rate, but every one of these was a missing piece of onboarding.

The obvious fix is the server instructions field. It helps, but the apps treat it differently:

We saw another production server send 115,077 characters of instructions (26,633 tokens). Grok Build passed the first 2,067. The rule that mattered most sat at character 28,484, so any app that cuts never showed it. Details: do AI agents read your MCP server instructions? and how long MCP server instructions should be (coming soon).

The server-only recipe

Four changes, all on the server. No skill, plugin or client setting is needed.

1. Instructions: say what the product is, then the hint, in under 2,000 characters

First line: what the product is and which questions it answers. Second: “Before your first call, call get_instructions with the job.” Then only the rules that must never be missed. Our recipe text was 728 characters, about 170 tokens, against the 5,092 characters the production server sent.

Acme Tasks: projects, tasks, people and activity for the user's team.
Use it for any question about the team's work, status or deadlines.
Before your first call, call get_instructions(job) once.
Never change or delete anything without the user's explicit request.

2. A get_instructions(job) tool

One argument, an enum of jobs (“plan_run”, “review_new”, “setup”…), returning that job's playbook: steps in order, which tools, what to confirm with the user. A one-enum schema keeps it tiny, which matters in apps that show only the cheapest tools first.

3. Always load it in Claude Code

Claude Code defers most MCP tools behind tool search. Set _meta: {"anthropic/alwaysLoad": true} on get_instructions (with a searchHint such as “how to use acme, playbook, help”). In our runs this cut Claude Code to one request of 6–7k tokens before the first call, against 2–3 requests and 15–28k without it.

4. One line at the start of every tool description

“Before your first call, call get_instructions once.” About 12 tokens per tool. It covers apps that cut or delay instructions: in Grok Build, the hint in instructions alone worked in 1 of 2 runs; with the line in descriptions, 2 of 2.

What the recipe did in runs

We tested on a local mock of the same 99-tool server: 232 runs, Claude Code and Codex, 18 Oct 2026. The prompts never mentioned instructions.

The tool alone wasn't the fix: without the hint, Claude Code went straight to a relevant-looking tool in 23 of 24 runs. Full breakdown, including which single parts did the most: make the agent read your playbook first: 24 of 24 runs.

Where each piece of knowledge goes

The production server's skills held 45.6 KB of knowledge. Every piece of it had a home on the server:

Don't rely on MCP prompts or resources for this: prompts weren't visible to the model in any app we captured, and resources only in some. See MCP prompts, resources and tools: which ones agents use. For error text that teaches, see error messages for AI agents.

Skills, plugins and AGENTS.md

Skills worked. In the same live trial they fixed both failures, and the agents followed the playbooks. But they cost tokens on the simplest job (Claude Code's skill run used about twice as many), they have to be installed per user and per app, and they drift from the server. Put the knowledge on the server first; a skill then becomes optional, not required. More in do you still need agent skills if you have an MCP server? (coming soon).

Guides in this section

• Make the agent read your playbook first: 24 of 24 runs

  The full experiment behind the recipe, part by part.

• Do AI agents read your MCP server instructions?

  Where each app puts your instructions, and where it cuts them.

Back to the overview: agent-ready tools.

How we measured

• Live trial: a 99-tool production MCP server, 3 read-only jobs × 2 conditions (with and without the product's skills) × 2 runs in Claude Code and Codex, 16 Oct 2026. Every call went through a read-only guard; 0 writes, 0 credits spent. Two runs per cell shows direction only.
• What reaches the model: a local stub serving the same tool list with unique marker words in each channel, real model calls, and traffic captured with a temporary, process-scoped proxy, 16–17 Oct 2026.
• Recipe test: a local mock of the same server, 232 runs in Claude Code and Codex, 18 Oct 2026, scored in code and read by hand. Ranges are 95% Wilson intervals.
• Limits: one product, mock data for the recipe test, one model per app, read-only jobs. Job and tool names in this guide are illustrative.