Multi-Tool MCP Workflows

What you'll learn

• Multi-tool workflows combine multiple MCP servers in one Claude Code session: GitHub for PRs, Filesystem for code, and Fetch for web docs
• Claude discovers and selects tools automatically across all connected servers; you do not need to route tasks manually
• Context flooding is the main risk: cap MCP output with MAX_MCP_OUTPUT_TOKENS and close servers you are not using
• The PR review + documentation update workflow is the canonical pattern; learn it once and adapt it to your stack

The problem: one server, one question, one answer is not how real work happens

The basic MCP lesson and the previous lesson showed you how to connect a single server and ask it a question. That works for "how many rows in the users table?" but it does not map to actual development tasks.

Consider a real PR review. You need to read the diff (GitHub), read the files the diff touches to understand their context (Filesystem), check if the changes align with the project's documentation (Notion or Filesystem again), and maybe look up the library version the PR introduces against upstream docs (Fetch or web). That is four different data sources, and every one of them lives behind a different MCP server.

One-server-at-a-time workflows force you into a manual loop: connect GitHub, get the diff, disconnect, connect Filesystem, read the files, disconnect, connect Notion, check the specs. You become the scheduler for your AI tools. The whole point of MCP is that you should not have to do that.

Multi-tool workflows solve this by running several MCP servers in the same session. Claude discovers the tools from all of them during startup, and it picks the right tool for each part of your request. You ask for a PR review with documentation context, and Claude calls GitHub, Filesystem, and Notion in whatever order makes sense.

Options & when to use each

Option	Good for	Costs	When to pick
GitHub + Filesystem combo	PR reviews, issue triage, codebase exploration with remote context. GitHub provides the diff and issue history; Filesystem provides the actual code and project structure.	Two persistent server processes. GitHub MCP requires a personal access token. Filesystem MCP needs a directory path argument.	Your primary workflow is code review or you need to correlate GitHub issues with the state of the codebase on disk.
GitHub + Filesystem + Fetch combo	Documentation updates, dependency research, cross-referencing code with upstream docs. Fetch reads web pages; Filesystem reads local files.	Three server processes. Fetch MCP can be chatty (every URL becomes a potential tool call). Set MAX_MCP_OUTPUT_TOKENS=50000 to cap output.	You update docs frequently or need Claude to verify claims against external sources (library changelogs, API docs, RFCs).
Postgres + Notion combo (covered in Connecting Business Data)	Business intelligence queries that span structured data (Postgres) and unstructured docs (Notion).	Connection pool usage, Notion API rate limits. Two servers competing for context window attention.	Your data lives in databases and your specs live in Notion. You want Claude to answer questions that cross that boundary.
Sequential single-server sessions	Simpler mental model, lower resource usage, no risk of tool conflict.	Manual: you must run separate sessions, copy results between them, and hold context in your head.	You only need one data source per task and do not mind the context switching. This is what the basic lessons teach; skip to the Build it section if you are ready for real workflows.

Build it

Workflow 1: PR review with GitHub + Filesystem

This workflow combines two servers. GitHub retrieves the PR diff and metadata. Filesystem reads the project files that the PR touches. Claude synthesizes both into a review.

Step 1: Register both servers.

# GitHub MCP (needs a token with repo access)
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token"
claude mcp add -s user github -- npx -y @modelcontextprotocol/server-github

# Filesystem MCP (scoped to your project directory)
claude mcp add -s project filesystem -- npx -y @modelcontextprotocol/server-filesystem /home/you/projects/myapp

Step 2: Verify both are connected.

claude mcp list
# github: connected (stdio)
# filesystem: connected (stdio)

Step 3: Run the review.

Start Claude Code and give it a multi-step request:

> Review PR #142 in the myorg/myapp repository. Read the diff, then read the full files that were changed, and give me a review that covers:
> 1. Logic errors or edge cases the diff might miss
> 2. Consistency with the rest of the codebase (check patterns in unchanged files nearby)
> 3. Missing tests

Claude will call GitHub's get_pull_request or get_diff tool first, then use Filesystem tools to open the affected files, then compose the review. The two servers work together: GitHub provides the diff as a list of changed files and line ranges; Filesystem reads those specific files.

What happens under the hood. Claude does not coordinate the servers. It receives the tool list at startup (GitHub tools + Filesystem tools as one flat catalog) and the LLM decides which tool to call based on the task description. It might call GitHub twice (get the diff, then get issue comments), Filesystem four times (each changed file), and interleave the calls in whatever order the task requires.

Cap the output to avoid context flooding. Three MCP servers can push a lot of text into the context window. Set a limit:

export MAX_MCP_OUTPUT_TOKENS=50000

This caps the total output from MCP tools. When a tool response exceeds the limit, Claude sees a truncated result with a note.

Workflow 2: Documentation update with GitHub + Filesystem + Fetch

This workflow combines three servers. Claude reads the current state of the code (Filesystem), checks open issues for changes that need documenting (GitHub), and verifies external references against live docs (Fetch).

Step 1: Add the Fetch MCP server.

claude mcp add -s user fetch -- npx -y @modelcontextprotocol/server-fetch

Step 2: Confirm all three are connected.

claude mcp list
# github: connected (stdio)
# filesystem: connected (stdio)
# fetch: connected (stdio)

Step 3: Give Claude a documentation task.

> The /api/v2/users endpoint changed in PR #203. Read the PR diff and the current implementation in src/routes/users.ts, then update docs/api-reference.md to reflect the new behavior. Check the Express.js v5 docs at expressjs.com to make sure our wording matches the framework's own terminology.

Claude will:

1. Call GitHub to get PR #203's diff
2. Call Filesystem to read src/routes/users.ts for the current implementation
3. Call Filesystem to read docs/api-reference.md for the current docs
4. Call Fetch to retrieve the relevant Express.js documentation page
5. Use Filesystem to write the updated documentation

All five steps happen in one session. You provide the context (which PR, which file, which endpoint); Claude handles the tool routing.

Workflow 3: Data-to-documentation pipeline with Postgres + Filesystem

A common pattern in data-heavy projects: query the database for current state, then generate documentation from the results.

claude mcp add -s local postgres -- npx -y @modelcontextprotocol/server-postgres "$DATABASE_URL"
claude mcp add -s project filesystem -- npx -y @modelcontextprotocol/server-filesystem /home/you/projects/myapp

Then:

> Query the Postgres database for all tables and their column definitions. Generate a data dictionary markdown file at docs/data-dictionary.md with a table per schema object. Include the row count for each table.

Claude queries Postgres for the schema metadata, queries again for row counts, then writes the result to the filesystem.

Designing your own multi-tool workflows

The pattern is the same regardless of which servers you combine:

1. Register all servers at the right scopes (user, project, or local).
2. Verify with claude mcp list that every server shows "connected."
3. Write a prompt that names the data sources explicitly. Claude is good at tool selection, but it helps to say "read the PR from GitHub and then read the affected files from the filesystem" rather than "review this PR" and hoping Claude discovers the two-step process on its own.
4. Set MAX_MCP_OUTPUT_TOKENS before launching a session with three or more servers. The default unbounded output can fill the context window with raw tool responses.
5. Close servers you do not need. claude mcp remove <name> before starting a session where that server would be noise. Fewer tools means faster tool selection and less context competition.

What goes wrong

Mistake	How you notice it	The fix
Context window flooded by MCP output	Claude's responses slow down and it starts forgetting earlier parts of the conversation. Responses get shorter or generic.	Set export MAX_MCP_OUTPUT_TOKENS=50000 before starting Claude Code. Remove servers you are not using. Break large tasks into smaller sessions.
Tools from two servers have overlapping names or purposes	Claude picks the wrong tool for a task (e.g., calling the Fetch server to read a local file instead of Filesystem)	Be more specific in your prompt: "use the filesystem server to read src/config.ts" rather than "read the config file." Claude generally routes correctly when the intent is clear.
GitHub MCP fails because the token has no repo access	claude mcp list shows "connected" but Claude reports authentication errors when calling GitHub tools	Generate a new token at github.com/settings/tokens with repo scope. Classic tokens need explicit scope selection; fine-grained tokens need per-repository access.
Filesystem MCP scoped to the wrong directory	Claude cannot find files you know exist	claude mcp remove filesystem and re-add with the correct absolute path. The Filesystem MCP server only sees files under the directory you pass as the argument.
Server process crashes mid-session	Claude stops calling that server's tools and reports "tool unavailable" or a transport error	Restart Claude Code. MCP servers are restarted on session start. If the crash is repeatable, check the server's logs (child process stderr) or test the command directly in a terminal.

Confirm it worked

Run a complete multi-tool workflow to verify the setup:

# 1. Verify all servers are connected
claude mcp list
# Expected output includes: github, filesystem (both "connected")

# 2. Run a PR review in print mode (replace with a real PR number)
claude -p "Review PR #1 in myorg/myapp. Read the diff via GitHub MCP and read the changed files via Filesystem MCP. List the files changed and note any logic issues."

# 3. If you also have Fetch MCP, verify it can retrieve a web page
claude -p "Use the Fetch MCP server to read https://example.com and tell me the page title."

# 4. List your servers after the session to confirm nothing crashed
claude mcp list

If step 2 returns a file list with observations, GitHub + Filesystem are cooperating. If step 3 returns a page title, Fetch is working. All three returning results means your multi-tool pipeline is functional.

Previous: Connecting Business Data to Claude CodeNext: MCP in Production