MCP Tools and Resources in Agent Workflows

1.Every connected server's tools, side by side

An agent doesn't choose a single MCP server to work with. Tools are discovered when each configured server connects, and the tools from all servers are available to the agent at the same time. The naming convention shows this. Each MCP tool is addressed as mcp__<server>__<tool>, so tools from a github server, a db server and a slack server all sit in one tool set. You can confirm what was discovered instead of assuming it. The SDK's init system message lists every tool in the session, and filtering on the mcp__ prefix shows what the servers added:

for await (const message of query({ prompt: "...", options })) {
  if (message.type === "system" && message.subtype === "init") {
    const mcpTools = message.tools.filter((name) => name.startsWith("mcp__"));
    console.log("Available MCP tools:", mcpTools);
  }
}

Discovery depends on connection, and servers connect at different speeds. Without tool search, Claude Code waits for every pending server before the first turn. A stdio server, or a remote server with no cached tool list, can hold that wait for up to MCP_TIMEOUT, which is 30 seconds by default. A remote server whose tool list was cached from a previous connection provides those tools from the first turn and connects the first time one of its tools is called. With tool search, which is the default, the startup wait covers only servers marked alwaysLoad: true. The other servers keep connecting in the background, and their tools become reachable once they connect.

By default the agent gets tools from every server. Narrowing that set is a deliberate choice. allowed_tools accepts a wildcard for a whole server or exact names for individual tools:

options = ClaudeAgentOptions(
    mcp_servers={
        # your servers
    },
    allowed_tools=[
        "mcp__github__*",  # All tools from the github server
        "mcp__db__query",  # Only the query tool from db server
        "mcp__slack__send_message",  # Only send_message from slack server
    ],
)

Sources1

2.Descriptions decide whether your tool gets picked

Your MCP tools share the tool set with Claude Code's built-in tools, such as Grep. In MCP, the information a tool gives about itself travels in the server's tools/list response. Each tool has a name, a title, a description, and an inputSchema whose properties can have descriptions of their own:

      {
        "name": "get_weather",
        "title": "Weather Information Provider",
        "description": "Get current weather information for a location",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name or zip code"
            }
          },
          "required": ["location"]
        },

A one-line description works for a weather tool that nothing else competes with. The exam guide is concerned with the case where a thin description competes with a built-in tool. Suppose an MCP tool that can search a codebase more capably than Grep is described in a few words. The agent tends to fall back on Grep. The fix the guide names is to expand the description: explain what the tool can do in detail and what its output contains, so the agent can see why it is the better choice. The sources for this lesson show where the description lives, but they don't document this preference effect or give a worked rewrite. Check the guidance against Anthropic's "Writing tools for agents" post.

Sources2

3.Resources: showing the agent what exists before it asks

Tools are what an agent calls. Resources are a separate server primitive: content the server exposes, with each item identified by a URI. A server that supports resources answers resources/list with a catalog. Each entry has a URI and a name, plus an optional title, description and MIME type. The server answers resources/read with the content at a given URI.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resources": [
      {
        "uri": "file:///project/src/main.rs",
        "name": "main.rs",
        "title": "Rust Software Application Main File",
        "description": "Primary application entry point",
        "mimeType": "text/x-rust"
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

This is the mechanism behind the exam guide's advice on content catalogs. Without resources, an agent that needs to know which issues, documents or tables exist has to find out with exploratory tool calls: list, search, list again. A server that publishes issue summaries, a documentation hierarchy or database schemas as resources gives the agent that map up front, and the agent then reads only the entries it needs. The spec leaves presentation to the client. A client can show resources in a tree or list for explicit selection, let the user search and filter them, or include them in context automatically, based on heuristics or the model's own selection.

Sources34

4.Adopt an existing server before writing one

For a standard integration, the cheapest server is one somebody already maintains. The Claude Code docs connect vendor-hosted servers such as Asana and Sentry with one claude mcp add command pointing at a URL, and they run published packages such as Playwright's with an npx command. The Agent SDK guidance follows the same split. If the vendor's docs give you a command, use stdio. If they give you a URL, use HTTP or SSE. Use an SDK MCP server only when you are building your own tools in code.

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

The exam guide's rule follows from this. For a standard system such as an issue tracker, use an existing community server. Save custom servers for workflows specific to your team, where no published server knows your conventions. The sources here show how little it costs to adopt an existing server. They don't name a Jira server or discuss the maintenance trade-offs, so treat Jira as the exam guide's example, not something the documentation states.

Sources15

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Claude Code always holds the first turn until every configured MCP server has connected.Why is that wrong?

   With tool search, the default, the startup wait covers only servers set to alwaysLoad: true. The others keep connecting in the background, and their tools become reachable when they connect.

   Covered in Every connected server's tools, side by side

2. 2.MCP resources are tools under another name, and the agent has to call them to find out what data exists.Why is that wrong?

   Resources are a separate primitive. A server lists them as a catalog of URIs through resources/list and returns content through resources/read, and the client decides how to surface them, for example as a browsable list the agent sees without exploratory calls.

   Covered in Resources: showing the agent what exists before it asks

Practise it for real

Add a project-scoped MCP server, take it through approval, and confirm its tools are available to Claude.

1. 1.From a repository root, run: claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

   Why: Project scope writes the server to .mcp.json, the file your teammates get when they clone.

   You should see: A .mcp.json at the project root with a claude-code-docs entry of type http.

2. 2.Run claude mcp list from your shell.

   Why: This shows each server's status, including project servers that haven't been approved yet.

   You should see: claude-code-docs is listed. If it shows Pending approval, the next step clears that.

3. 3.Start claude, approve the server if prompted, then run /mcp.

   Why: A project-scoped server loads only after you approve it, and /mcp shows the live connection status.

   You should see: claude-code-docs shows as connected.

4. 4.Ask: Use the claude-code-docs server to look up what MCP_TIMEOUT does

   Why: This confirms the server's tools were discovered and can be used next to the built-in tools.

   You should see: Claude calls a tool from the claude-code-docs server and answers from its result.

5. 5.Run: claude mcp remove claude-code-docs --scope project

   Why: Removing with an explicit scope avoids leaving a stale definition behind in another scope.

   You should see: The entry disappears from .mcp.json and from claude mcp list.