Build Your First AI Agent with the Claude Agent SDK

Step 6: Manage Your MCP Servers

Once configured, you can manage your MCP servers with these commands:

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get my-first-server

# Remove a server
claude mcp remove my-first-server

Project-scoped servers from .mcp.json that are awaiting your approval appear in claude mcp list and claude mcp get <name> as ⏸ Pending approval (run 'claude' to approve). Run claude interactively to review and approve them. claude mcp get <name> shows rejected servers as ✘ Rejected (see disabledMcpjsonServers in settings).

As of v2.1.196, claude mcp list and claude mcp get read .mcp.json approvals only from settings files that are not checked into the repository until you trust the workspace by running claude in it and accepting the workspace trust dialog. A cloned repository cannot approve its own servers: enableAllProjectMcpServers or enabledMcpjsonServers committed to the project's .claude/settings.json is ignored in an untrusted folder, and the server stays at ⏸ Pending approval instead of being connected and health-checked. Approvals from these sources still apply in an untrusted folder:

• your user ~/.claude/settings.json
• managed settings
• settings passed with --settings

Approvals in an untracked .claude/settings.local.json also apply, but only after you accept a trust dialog for that folder or one of its parent directories: Claude Code runs git to check whether the file is tracked, and it runs that check only in a trusted folder. In a folder you have never trusted, the file's approvals wait for the trust dialog unless the folder is your own configuration home: your home directory, or a directory whose .claude you have set as CLAUDE_CONFIG_DIR. Before v2.1.207, an untracked .claude/settings.local.json approved servers in a folder you had never trusted. A disabledMcpjsonServers entry in any settings file still rejects the server.

Inside a Claude Code session, check server status with:

/mcp

The /mcp panel shows the tool count next to each connected server and flags servers that advertise the tools capability but expose no tools. A remote server whose configuration has an empty url shows as not configured in /mcp, in claude mcp list, and in the /plugin manager, and Claude Code does not attempt to connect to it. A plugin can include a placeholder entry like this for a connector you configure later, so Claude Code does not report it as an error or a setup issue. The server's detail view in /mcp reads No URL configured for this server; set the entry's url to connect it. Before v2.1.208, Claude Code reported an empty url as a configuration issue with a prompt to reconnect.

If your request needs tools from a server that is still connecting in the background, Claude waits for that server before continuing. With tool search enabled, which is the default, the wait happens inside the ToolSearch call. In configurations without tool search, such as Google Cloud's Agent Platform, a custom ANTHROPIC_BASE_URL, or ENABLE_TOOL_SEARCH=false, Claude uses the WaitForMcpServers tool instead.

Some server names are reserved for Claude Code's built-in servers: workspace, claude-in-chrome, computer-use, Claude Preview, and Claude Browser. If your configuration defines a server with a reserved name, Claude Code skips it at load time and shows a warning asking you to rename it. claude mcp add rejects a reserved name with an error. Claude Preview and Claude Browser both name the built-in server that the Claude Code desktop app's preview pane uses. Before v2.1.205, Claude Browser was not reserved, so a user-configured server could register under that name.

Step 7: Run Your First Agent Task

Now that your MCP server is configured, start a Claude Code session and give it a task that uses your custom tools.

claude

Inside the session, try a task like:

Use my-first-server to list available tools and then run the hello-world tool.

Claude will discover the tools from your server and execute them. You should see output from your server's tools in the conversation.

For a more practical example, if you have a database server connected, you could ask:

Query the database for the 10 most recent users and summarize their activity.

Step 8: Build a Custom Agent with the Agent SDK

The Agent SDK lets you build fully custom agents powered by Claude Code's tools and capabilities, with full control over orchestration, tool access, and permissions. While the SDK itself is a programmatic interface, you can achieve similar results using Claude Code's built-in agent team capabilities.

Spawn Subagents

You can spawn multiple Claude Code agents that work on different parts of a task simultaneously. A lead agent coordinates the work, assigns subtasks, and merges results. To run several full sessions in parallel and watch them from one screen, use background agents.

Inside a Claude Code session, you can ask:

Spawn two subagents: one to write tests for the auth module, and another to refactor the database layer. Have them report back to me when done.

Claude Code will orchestrate the subagents, each running in its own context, and merge their results.

Pipe and Script with the CLI

Claude Code is composable and follows the Unix philosophy. You can pipe logs into it, run it in CI, or chain it with other tools:

# Analyze recent log output
tail -200 app.log | claude -p "Slack me if you see any anomalies"

# Automate translations in CI
claude -p "translate new strings into French and raise a PR for review"

# Bulk operations across files
git diff main --name-only | claude -p "review these changed files for security issues"

Automate Workflows

Create skills to package repeatable workflows your team can share, like /review-pr or /deploy-staging. Hooks let you run shell commands before or after Claude Code actions, like auto-formatting after every file edit or running lint before a commit.

Step 9: Connect to External Tools via MCP

Once your MCP server is connected, you can ask Claude to interact with external systems. Here are some examples from the documentation:

• "Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub."
• "Check Sentry and Statsig to check the usage of the feature described in ENG-4521."
• "Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database."
• "Update our standard email template based on the new Figma designs that were posted in Slack."
• "Create Gmail drafts inviting these 10 users to a feedback session about the new feature."

An MCP server can also act as a channel that pushes messages into your session, so Claude reacts to Telegram messages, Discord chats, or webhook events while you are away.

Verifying It Works

To confirm your agent is functioning correctly:

1. Run claude mcp list and verify your server appears with a connected status (not pending or rejected).
2. Inside a Claude Code session, run /mcp and check that your server shows the expected number of tools.
3. Ask Claude to use a specific tool from your server and verify it executes without errors.
4. Check that Claude's response includes the output from your tool, not a generic error message.
5. If your server supports dynamic tool updates, modify your server code to add a new tool, and verify Claude discovers it without restarting the session. Claude Code supports MCP list_changed notifications, allowing MCP servers to dynamically update their available tools, prompts, and resources without requiring you to disconnect and reconnect. When an MCP server sends a list_changed notification, Claude Code automatically refreshes the available capabilities from that server.

Common Problems

Installation Fails with Syntax Error

If you see syntax error near unexpected token ' during installation, you are likely in the wrong shell. Check your prompt: PS C:\ means PowerShell, C:\ without PS means CMD. Use the correct install command for your shell.

MCP Server Shows as Pending Approval

If your server appears as ⏸ Pending approval, you need to run claude interactively in the project directory and accept the workspace trust dialog. Project-scoped servers from .mcp.json require explicit approval. As of v2.1.196, approvals committed to the project's .claude/settings.json are ignored in an untrusted folder.

MCP Server Fails to Connect

If an HTTP or SSE server disconnects mid-session, Claude Code automatically reconnects with exponential backoff: up to five attempts, starting at a one-second delay and doubling each time. The server appears as pending in /mcp while reconnection is in progress. After five failed attempts the server is marked as failed and you can retry manually from /mcp. Stdio servers are local processes and are not reconnected automatically.

The same backoff applies when an HTTP or SSE server fails its initial connection at startup. As of v2.1.121, Claude Code retries the initial connection up to three times on transient errors such as a 5xx response, a connection refused, or a timeout, then marks the server as failed if it still cannot connect. Authentication and not-found errors are not retried because they require a configuration change to resolve.

When a configured server fails to connect, Claude Code tells Claude which server failed and its connection error, including in ToolSearch results that find no matching tool, so Claude reports the connection failure in its response. Requires tool search, which is enabled by default. In configurations without tool search, such as a custom ANTHROPIC_BASE_URL, ENABLE_TOOL_SEARCH=false, or a model that does not support tool search, and on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry, Claude Code does not report failed server connections to Claude. Before v2.1.205, Claude Code did not pass connection errors to Claude, and Claude could respond as if the failed server's tools were never configured.

MCP Tool Output Too Large

Claude Code displays a warning when MCP tool output exceeds 10,000 tokens and limits output to 25,000 tokens by default. To raise the limit, set the MAX_MCP_OUTPUT_TOKENS environment variable (for example, MAX_MCP_OUTPUT_TOKENS=50000); the warning threshold is fixed.

Tool Call Times Out

A tool call to an MCP server that sends no response and no progress notification for the idle window aborts with an error instead of waiting for the wall-clock limit. The idle timeout requires Claude Code v2.1.187 or later. It applies to every server type except IDE servers and SDK in-process servers. The idle window defaults to five minutes for HTTP, SSE, WebSocket, and claude.ai connector servers, and to 30 minutes for stdio servers. Before v2.1.203, stdio servers were exempt from the idle timeout. Set the CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT environment variable in milliseconds to change the idle window, or set it to 0 to disable the check.

Set a per-server tool execution timeout by adding a timeout field in milliseconds to that server's .mcp.json entry, for example "timeout": 600000 for ten minutes. This overrides the MCP_TOOL_TIMEOUT environment variable for that server only. The per-server timeout is a hard wall-clock limit per tool call, and progress notifications from the server do not extend it. Values below 1000 are ignored and fall through to MCP_TOOL_TIMEOUT, or to its default of about 28 hours when that variable is unset.

For an HTTP, SSE, or claude.ai connector server there is also a second, per-request timer that covers each request through to the server's first response byte. That timer is 60 seconds unless you set the per-server timeout or MCP_TOOL_TIMEOUT; setting either to 60 seconds or higher raises the per-request timer to that value, a lower value does not shorten it, and the 28-hour default of an unset MCP_TOOL_TIMEOUT never feeds it. Stdio and WebSocket servers have no per-request timer. Before v2.1.162, values below 1000 were floored to one second instead.

Plugin Not Found

If /plugin install mcp-server-dev@claude-plugins-official reports that the plugin is not found, your local copy is outdated. Refresh it with /plugin marketplace update claude-plugins-official and retry the install.

Reserved Server Name

If you try to add a server with a reserved name (workspace, claude-in-chrome, computer-use, Claude Preview, or Claude Browser), claude mcp add rejects it with an error. Choose a different name.

JSON Configuration Error

A JSON entry that has a url but no type is a configuration error. Claude Code skips that server and reports MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. Before v2.1.202, this was reported as command: expected string, received undefined.

Next Steps

1. Build a Custom MCP Server: Use the mcp-server-dev plugin to build a server that connects to your team's specific tools, such as a project management system or a monitoring dashboard. The plugin scaffolds a remote HTTP or local stdio server based on your use case.

2. Create Skills for Repeatable Workflows: Package common tasks like code review, deployment, or dependency updates into skills that your team can share. Skills use the same MCP infrastructure and can include custom tools.

3. Set Up Scheduled Tasks: Use Routines or Desktop scheduled tasks to run Claude on a schedule for morning PR reviews, overnight CI failure analysis, weekly dependency audits, or syncing docs after PRs merge. Routines run on Anthropic-managed infrastructure, so they keep running even when your computer is off.

4. Explore the Agent SDK for Custom Orchestration: For fully custom workflows, the Agent SDK lets you build your own agents powered by Claude Code's tools and capabilities, with full control over orchestration, tool access, and permissions. Review the official Agent SDK documentation for programmatic agent construction.