--- title: How to Onboard AI Agents Through Your MCP Server description: OAuth lets an agent in but doesn't teach it your product. A server-only onboarding recipe for MCP: instructions, get_instructions, hints. 24/24 runs. canonical: https://spiritroom.app/guides/onboard-agents-through-mcp/ published: 2026-10-21 updated: 2026-10-21 --- > Markdown version of https://spiritroom.app/guides/onboard-agents-through-mcp/ for agents. Index: /llms.txt [Spirit Room](/) / [Guides](/guides/agent-ready-tools/) # 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 **TL;DR** - **Onboarding an agent is not the same as authorising it.** In a live trial on a 99-tool production server, 2 of 12 runs without extra skills failed: one Codex run didn't recognise the product and made 0 calls; another reached for a paid tool during a read-only job. - **You can't rely on server instructions alone.** Claude Code cuts them at 4,096 characters, Grok Build at about 2,048, and Codex puts them inside every tool description instead of the first prompt. - **A server-only recipe fixed it on a mock:** a short hint in the instructions, a `get_instructions(job)` tool, an always-load flag and one line in each tool description. The playbook was read first in 24 of 24 runs in both Claude Code and Codex (86–100%), against 1 of 24 and 9 of 24 without the hint. - **It picks the right playbook and stays quiet when it should:** right job 79/79 and 70/70; an off-topic prompt never triggered a call (15/15). - **Then keep teaching after the first call:** field meanings in descriptions, next-step hints in results, and errors that explain the right path. [What agent onboarding means](#what)[How onboarding fails today](#fails)[The server-only recipe](#recipe)[What the recipe did in runs](#results)[Where each piece of knowledge goes](#where)[Skills, plugins and AGENTS.md](#skills)[Guides in this section](#guides)[How we measured](#how-we-measured)[FAQ](#faq) ## 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”? Connected (OAuth)**→**Recognises the product**→**Reads the playbook first**→**Keeps the house rules**→**Job done ## 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: What happens to your server instructions, by app (captured 16 Oct 2026) | App | Where instructions go | Limit seen | | --- | --- | --- | | Claude Code 2.1.301 | System prompt | Cut at 4,096 characters | | Codex 0.161 | Prepended to every tool description, not in the first prompt | None seen | | Grok Build 1.0.60 | A reminder at session start | Cut at about 2,048 characters; once arrived too late | | OpenCode 1.18.34 | System prompt | Full text | 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?](/blog/do-agents-read-mcp-server-instructions/) and [how long MCP server instructions should be](/blog/mcp-server-instructions-length/). **Find out what agents learn from your server in their first five minutes.** We run your users' real jobs through Claude Code, Codex and the other apps they use, show what reaches the model, and test an onboarding recipe against a baseline, with pass rates and confidence ranges. [Book a pilot →](/#contact) ## 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. Claude Code, tool only, no hint*1/24* Codex, tool only, no hint*9/24* Claude Code, full recipe*24/24* Codex, full recipe*24/24* Mock results, 95% confidence ranges | Check | Claude Code | Codex | | --- | --- | --- | | Playbook read first, no hint | 1/24 (1–20%) | 9/24 (21–57%) | | Playbook read first, full recipe | 24/24 (86–100%) | 24/24 (86–100%) | | Asked for the right job's playbook | 79/79 (95–100%) | 70/70 (95–100%) | | Off-topic prompt, no call | 15/15 (80–100%) | | | Vague request, full recipe | 4/4 (51–100%), against 2/4 and 1/4 without the hint | | 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](/blog/get-instructions-first-24-of-24/). ## 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: From skills to the server | Knowledge | Server-side home | | --- | --- | | What the product is, which questions it answers | Instructions, first line | | Rules: read before you write, confirm spending, don't add up totals that overlap, the product's own words | Instructions, under 2,000 characters | | Step-by-step playbooks per job | `get_instructions(job)` | | What each field means | The description of the tool that returns it | | What to do next (“now preview the plan”, “store this cursor”) | Next-step hints in results | | Paid tools during read-only work, writes without a version | Errors and refusals that explain the right path | 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](/blog/mcp-prompts-resources-tools-which-agents-use/). For error text that teaches, see [error messages for AI agents](/blog/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?](/blog/agent-skills-vs-mcp-server/). ## Guides in this section - [Make the agent read your playbook first: 24 of 24 runs](/blog/get-instructions-first-24-of-24/) The full experiment behind the recipe, part by part. - [Do AI agents read your MCP server instructions?](/blog/do-agents-read-mcp-server-instructions/) Where each app puts your instructions, and where it cuts them. **Go deeper:** [Agent skills vs an MCP server](/blog/agent-skills-vs-mcp-server/), [How long server instructions should be](/blog/mcp-server-instructions-length/), [When the agent doesn't recognise your server](/blog/agent-does-not-recognise-mcp-server/), [Agent onboarding for SaaS beyond OAuth](/blog/saas-agent-onboarding-beyond-oauth/). Back to the overview: [agent-ready tools](/guides/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. ## FAQ ### How do I onboard AI agents to my product via MCP? Put the onboarding in the server. Start the server instructions with what the product is and a hint to call a get\_instructions tool before anything else, keep the text under about 2,000 characters, add a get\_instructions(job) tool that returns the playbook for each job, mark it always-load for Claude Code, and add one line to every tool description telling the agent to call it first. On a mock this got the playbook read first in 24 of 24 runs in both Claude Code and Codex. ### Isn't OAuth enough to onboard an agent? OAuth gets the agent connected and authorised. It doesn't tell the agent what your product is for, which tool to start with, or which rules to keep, such as asking before spending credits. In our live trial a connected, authorised Codex still asked the user which platform they meant and made no calls. ### Do AI agents read MCP server instructions? Yes, but not all of them and not in the same place. Claude Code puts them in the system prompt and cuts them at 4,096 characters, Grok Build cuts them at about 2,048, Codex prepends them to every tool description, and OpenCode passes them in full. Put the critical rules in the first 2,000 characters. ### What should a get\_instructions tool return? The playbook for one job: the steps in order, which tools to use, what to check before writing or spending, and what to tell the user. Give it a single enum argument for the job, so its schema stays tiny and apps that show only some tools still show it. ### Do I still need agent skills if I have an MCP server? Not if the server carries what the skills say. Skills fixed real failures in our trial, but every piece of their knowledge had a server-side home: instructions, get\_instructions, tool descriptions, next-step hints and errors. Server-side, it works in every app that connects, not only the one where the skill is installed. ### Will a get\_instructions hint make the agent call it for unrelated questions? Not in our runs. With the full recipe loaded, an off-topic prompt never triggered a call in 15 of 15 runs. **Find out what agents learn from your server in their first five minutes.** We run your users' real jobs through Claude Code, Codex and the other apps they use, show what reaches the model, and test an onboarding recipe against a baseline, with pass rates and confidence ranges. [Book a pilot →](/#contact) ## Keep reading - Up[How to make your MCP server or API agent-ready, with proof (guide hub)](/guides/agent-ready-tools/) - Related[Make the agent read your playbook first: 24 of 24 runs in Claude Code and Codex](/blog/get-instructions-first-24-of-24/) - Related[Do AI agents read your MCP server instructions? Tested in Claude Code, Codex, Grok and OpenCode](/blog/do-agents-read-mcp-server-instructions/) - Related[Do you still need agent skills if you have an MCP server? 24 live runs with and without](/blog/agent-skills-vs-mcp-server/) - Related[How long should MCP server instructions be? Why 115,000 characters reached the model as 2,067](/blog/mcp-server-instructions-length/) - Related[MCP prompts vs resources vs tools: which ones agents actually see (tested in 5 agent apps)](/blog/mcp-prompts-resources-tools-which-agents-use/) - In this guide[When the agent doesn't know your MCP server is the right tool (“Which product do you mean?”)](/blog/agent-does-not-recognise-mcp-server/) - In this guide[Agent onboarding for SaaS: OAuth gets the agent in, it doesn't tell it what to do](/blog/saas-agent-onboarding-beyond-oauth/)