Core Concepts

How AI Agents Discover and Execute Actions on Your Site

⏱ 10 min

The previous two lessons covered abilities and MCP as separate concepts. This lesson connects them end to end: the exact sequence of events between an AI client opening a connection and your execute_callback actually running.

Prerequisites

Understanding Abilities and MCP Core Concepts, the two previous lessons. Still no code to run, this is the request lifecycle you’ll see in action once you build a real server in Course 2.

The full lifecycle, step by step

From connection to executed action
1
Client connects and initializes
An AI client (Claude Desktop, Cursor, a custom script) opens a connection to your site's MCP endpoint, over Streamable HTTP or stdio, and sends an initialize request with its supported protocol version.
2
MCP Adapter responds with server capabilities
Your site confirms the protocol version it supports and what it offers, in practice, that it has tools available.
3
Client lists available tools
The client asks "what tools do you have?" The MCP Adapter answers with every ability that has meta.mcp.public set to true, converted into MCP tool definitions (label to title, schemas, annotation hints).
4
The model decides to call a tool
Based on the user's request and each tool's description, the AI model (not the client app itself) decides which tool to call and with what arguments, this is why writing a clear ability description matters so much.
5
MCP Adapter runs permission_callback first
Before anything else happens, WordPress checks whether the authenticated user (or the connection's credentials) actually has permission to run this ability. If this returns false, execution stops here.
6
execute_callback runs
Only if the permission check passed, your actual PHP logic runs and returns a result matching output_schema.
7
Result flows back to the model
The MCP Adapter returns the result over the same connection, the model incorporates it into its response to the user.

Why the description field matters more than it looks

Step 4 is where a detail from Lesson 3 becomes important in practice: the AI model chooses which tool to call based on reading each tool’s label and description, it doesn’t have access to your PHP code, only to that text. An ability described as "Handles posts" gives the model almost nothing to work with. An ability described as "Publishes a new blog post given a title and body, sets it to draft status by default" gives the model exactly what it needs to decide correctly, and just as importantly, to decide when not to use it.

Why permission checks run before execution, every time

This ordering (Step 5 before Step 6) isn’t an implementation detail, it’s the entire security model. The MCP Adapter never runs your execute_callback on good faith that the caller is allowed to. Every single invocation, regardless of what the AI model “intended,” is checked against permission_callback first. This is also exactly why permission_callback needs to check the real, current user or credential, not some cached or assumed state, Course 4 covers this in depth.

What “discovery” actually means in practice

When people say an AI agent “discovers” what a site can do, this is literally what they mean: Step 3, the client asking for the tool list, and the model reading through the results. There’s no separate crawling or scanning happening, the entire discovery surface is whatever abilities you’ve registered with meta.mcp.public set to true. Nothing else on your site is visible to the agent through this mechanism at all.

Assuming an agent can see more than its tool list

A common misconception is that once connected, an AI agent has some general awareness of your site. It doesn’t. Its entire knowledge of your site is the tool list from Step 3, plus whatever data individual tool calls return. If an ability isn’t registered and exposed, it doesn’t exist from the agent’s point of view, full stop.

Recap

An agent’s interaction with your site follows a fixed sequence: connect, initialize, list tools, the model chooses one based on its description, WordPress checks permission, then executes, then returns a result. Nothing is visible to the agent that you haven’t explicitly registered and exposed, and nothing executes that hasn’t passed a permission check first.

Resources & further reading

← MCP Core Concepts: Tools, Resources, and Prompts Controlling Visibility: Ability Categories and the meta.mcp.public Flag →