The animated scenes show on a laptop or desktop screen.
MCP servers
MCP servers in Claude Code and agents
Razorpay's payments platform team wants Claude Code to read Jira tickets and the payments ledger itself, so that its 40 engineers stop pasting them into the chat. An MCP server is a separate program that gives Claude Code the tools of one outside system, such as Jira. This chapter connects three MCP servers for the whole team and follows each problem the team runs into on the way. It shows where each server's entry belongs and what a server has to tell Claude before Claude uses its tools.
What this chapter shows you
- An MCP server gives Claude Code the tools of one outside system. Claude Code finds every server's tools when it connects, and the team builds only the one server that no vendor can publish.
- Team servers go in
.mcp.json, and tokens stay out of it. A server added on one laptop never reached the new joiner, and a token typed into the file reached 40 laptops and the git history. - A personal server goes in
~/.claude.json, and Claude uses every server's tools in one session. One engineer moves her experimental server out of the team's file, and Claude uses tools from four servers in one session. - Claude uses a team server when it can tell what the server offers. Claude picks Grep over a tool whose description is one line long, and with resources Claude finds a column in two calls instead of eight.
- Check yourself. Choose what belongs in the team's file, then answer one question in the exam's style.
Part 1: An MCP server gives Claude Code the tools of one outside system
Razorpay's payments platform team from chapters 2 to 4 is about 40 engineers in Bengaluru. They work in one , payments-platform, with a folder for each service (services/checkout, services/refunds, services/transfers) and shared code in libs/money. Every engineer runs , Anthropic's coding tool, in a on their own laptop, and each run of it is one .
Tickets are kept in , code is kept on , and every refund's history is recorded in Razorpay's internal . When the tech lead picks up ticket PAY-2817, she copies the ticket's text from Jira into the chat, then copies the refund's rows from the screen that shows the ledger. She wants Claude Code to read both itself. Anthropic's Claude Code documentation gives this as the reason to connect a server: Connect a server when you find yourself copying data into chat from another tool, like an issue tracker or a monitoring dashboard.
An MCP server is a separate program that gives Claude the tools of one outside system.
An is a separate program that gives Claude a set of , and sometimes content Claude can read, for one outside system such as Jira. , the Model Context Protocol, is the open standard that sets how Claude Code and a server exchange messages, so a server written once works with Claude Code, with agents built on Anthropic's , and with any other program that uses MCP.
The team wants three servers: jira for tickets, github for code reviews and , and ledger for the payments ledger. The names are the ones the team gives the servers when it adds them.
When a session starts, Claude Code connects to every server it is configured with and sends each one a request, which asks the server for the list of its tools. Each server replies with its tools: their names, descriptions and inputs. Claude Code adds them to its , such as Read, Edit, and , and from then on Claude can ask for a Jira tool the same way it asks for Read. As in chapter 1, Claude asks for the tool, Claude Code sends the call to the server, and the server sends the request to Jira's API.
Some servers run on other machines, the vendor's or the team's own, and Claude Code reaches them at an address over . Atlassian runs its Jira server on Atlassian's machines, and the team runs its ledger server on Razorpay's. Claude Code starts other servers as programs on the engineer's laptop and exchanges messages with each one through that program's input and output. These are called servers, after “standard input and output”. The team runs GitHub's server this way, on each laptop, from the package GitHub publishes.
MCP servers
When the tech lead works on PAY-2817, she copies the ticket's text from Jira and the refund's rows from the ledger screen, and pastes both into the chat. Claude reads what she pasted, and for the next ticket she has to copy again.
The tech lead connects Atlassian's Jira server to Claude Code, signs in to Atlassian once and starts a new session. Claude Code asks the server which tools it offers, a request called tools/list, and the server replies with tools such as getJiraIssue and searchJiraIssuesUsingJql.
She asks Claude to read PAY-2817 and pastes nothing. Claude asks for getJiraIssue, Claude Code passes the call to the Jira server, the server fetches the ticket from Jira, and Claude Code hands the ticket to Claude.
She connects the GitHub and ledger servers the same way, because every server uses the same protocol, MCP. In her next session Claude Code asks all three servers for their tools at once, and GitHub's create_pull_request and pull_request_read and the ledger's search_ledger join the Jira tools.
In one Claude Code session, Claude has its built-in tools and the tools of three MCP servers. Claude Code reaches the Jira and ledger servers over the network and starts the GitHub server on the laptop, and each server keeps its own connection to Jira, GitHub or the ledger.
Adding the second and the third server took the same step as adding the first, because every server uses the same protocol.
Claude sees each MCP tool under a longer name that also says which server it came from. This is the list of tools Claude has in a payments-platform session once the three servers have connected:
Read Edit Grep BashFour of Claude Code's built-in tools, as the exam guide lists them.
mcp__jira__getJiraIssue
mcp__jira__searchJiraIssuesUsingJqlTwo of the tools Atlassian's Jira server offers: one reads a single ticket, and the other searches tickets using Jira's query language, JQL. Each name is mcp__, then the server's name in Razorpay's setup, then two underscores, then the tool's own name on that server. The server's name keeps two servers' tools apart even when they have a tool with the same name.
mcp__github__create_pull_request
mcp__github__pull_request_readTwo of the tools GitHub's server offers: one opens a pull request and one reads a pull request.
mcp__ledger__search_ledgerThe one tool the team's own server offers so far.
MCP servers: Claude Code finds every server's tools when it connects
An engineer who has already signed in to Atlassian starts Claude Code in payments-platform. Claude Code connects to the three servers it is configured with, jira, github and ledger, and sends each one a tools/list request.
Each server replies with its tools. Claude Code adds them to its list beside the built-in ones, each named mcp__, then the server's name, two underscores and the tool's name.
The engineer types “Read PAY-2817 and tell me what it asks for.” Claude Code sends the request to Claude through the API, and its tool list carries the built-in tools and every MCP tool.
Claude asks for mcp__jira__getJiraIssue with PAY-2817. Claude Code sends the call to the jira server, which reads the ticket from Jira Cloud, and the ticket goes back to Claude in the next request.
Claude writes its answer, and Claude Code prints it in the terminal: PAY-2817 asks for a fix to refunds that stay in processing after the bank sends them back with a reversal code.
Claude Code found every MCP tool when the session started, by asking each server, and Claude asked for one of them the same way it asks for Read.
Claude Code holds the connection to each server, and each server holds its own connection to its system. Claude sends only the tool's name and its inputs.
The exam guide's model, which the drawings show and the exam marks, is that Claude Code finds every connected server's tools when the session starts, puts each tool's definition in the request, and keeps all of them available in the same session. As of 22 October 2026, Claude Code turns on by default, which changes only when the full definitions arrive. At the start of a session Claude Code loads each MCP tool's name. When Claude needs a tool, it searches the tool names and descriptions, and Claude Code fetches that tool's full definition. Every connected server's tools are still available in the same session, and Claude still chooses a tool by reading its description, so the rest of this chapter applies with tool search on or off.
Use the vendor's server for Jira and GitHub, and build a custom server only for the ledger.
For a common system such as Jira or GitHub, the company that makes it usually publishes its own MCP server and keeps it up to date with its own . The exam guide's phrase for these is ; it covers any ready-made server, whether the system's vendor or another developer wrote it. A is code the team writes itself, and then has to secure and change every time the outside system changes.
One engineer proposes writing razorpay-jira-mcp, so that the team “controls the integration”. Atlassian already publishes a server for Jira, and GitHub publishes one for GitHub. Nobody outside Razorpay can publish a server for the payments ledger, because only the team knows its tables and who may read them.
Adding an existing server takes one command with the address its maker publishes, which Part 2 shows. The exam guide's rule is to choose existing servers for standard integrations such as Jira and to keep custom servers for team-specific work, so the team's own effort goes into ledger.
Existing servers and custom servers
Atlassian publishes an MCP server for Jira, and GitHub publishes one for GitHub. The team connects Atlassian's server, and one engineer builds his proposed Jira server, razorpay-jira-mcp, and connects it beside Atlassian's so the team can compare the two.
Jira's API changes. Atlassian updates its own server, so the team's connection keeps working with no work from the team. The homemade server stops working with the new API, and because it handles its own access to Jira, the team must also review its security itself.
The team drops razorpay-jira-mcp and takes GitHub's published server too. It spends its own time on ledger, a server for Razorpay's internal payments ledger, which no vendor can publish.
The team uses existing servers for Jira and GitHub, and their makers keep them up to date. It writes a custom server only for the ledger, which nobody outside Razorpay can serve.
Existing servers and custom servers: each vendor maintains its own server (illustrative months)
Over six months, Jira's API changes twice. Each time Atlassian updates its jira server at the same address, and the team's entry for it does not change.
Had the team kept razorpay-jira-mcp, each change would have been a pull request for the team and a security review too, because that server handles its own access to Jira. Atlassian's server already gives Claude the same tools.
The team drops the proposal. Its pull requests go into ledger: building the server, adding search_ledger, and later describing the ledger's tables for Claude.
Atlassian handled both changes to Jira's API inside its own server, so the team's time went only into the server that no vendor could write.
The team did not reach this setup in one step. It started with one server on one laptop.
Part 2: Team servers go in .mcp.json, and tokens stay out of it
Where a server's entry is written sets who gets the server.
Adding a server writes a short entry, the server's name and how to reach it, into a configuration file. A server's is where that entry is written: the file, and the place in that file, that holds it. The scope sets which engineers get the server and in which projects.
An entry in , a file at the root of payments-platform, has . The file is to with the rest of the , so the entry reaches every engineer who or the repository. , Claude Code's own configuration file in an engineer's , holds the other two scopes, and it stays on that engineer's laptop, because git copies only what is inside the repository. An entry inside one project's section of that file has : it serves one engineer in one repository, and claude mcp add writes there when no scope is given. An entry at the top level of the file has : it serves one engineer in every repository on that laptop.
The exam guide names two scopes, and exam questions use these two: project scope for servers the whole team shares, and user scope for a server one engineer wants for personal use or is trying out. As of 22 October 2026, Claude Code also has local scope, which the exam guide does not name, and claude mcp add uses it when no scope is given. jira, github and ledger are team servers, so all three belong in .mcp.json.
project scope
.mcp.json, at the repository rootCommitted with the code, so every engineer who clones or pulls the repository gets the server. Use it for team servers such as jira, github and ledger. The exam guide names this scope.
user scope
~/.claude.json, at the top levelKept on one engineer's laptop, and the server loads in every project that engineer opens there. Use it for a personal or experimental server. The exam guide names this scope.
local scope
~/.claude.json, in one project's sectionKept on one engineer's laptop, and the server loads in that one project only. claude mcp add writes here when the command names no scope. Claude Code has this scope as of 22 October 2026, and the exam guide does not name it.
The tech lead's first command adds the Jira server to her laptop only.
The tech lead copies the command from Atlassian's setup page and runs it in her , with the server named jira:
claude mcp add --transport http jira \Add an MCP server named jira that Claude Code reaches over the network using . The backslash continues the command on the next line.
https://mcp.atlassian.com/v2/mcpThe address of Atlassian's Jira server, from Atlassian's setup page.
Each engineer signs in to Atlassian with their own account once, from Claude Code's panel, and Claude Code stores the sign-in and renews it, so no password or , the secret string that proves who is signing in, is written in .mcp.json or any other file the team shares. After the tech lead signs in, Claude can read PAY-2817 directly in her . The command , run in the terminal, lists every server Claude Code is configured with and the status of each, and the /mcp panel inside a session shows the same. On Monday a new joiner clones payments-platform, asks Claude Code to read PAY-2817, and his session has no jira server.
The new joiner's session has no jira server. Where should the entry go so that every engineer who clones payments-platform gets it: in the tech lead's ~/.claude.json, in .mcp.json, or in ?
Write the entry in .mcp.json and commit it.
With no --scope, claude mcp add wrote the entry into the tech lead's ~/.claude.json, in the section for the payments-platform folder on her laptop, which is local scope. The entry worked for her and nobody else.
The fix is to write the entry in .mcp.json and commit it. The usual way is to run the same command with --scope project, which writes the entry into .mcp.json itself, including the line "type": "http":
claude mcp add --transport http jira \The same command as before, adding a server named jira reached over HTTP.
--scope project https://mcp.atlassian.com/v2/mcp--scope project writes the entry into .mcp.json at the repository root, so it can be committed with the code.
The tech lead writes the file by hand instead. On her first try she pastes the snippet Atlassian publishes for Claude's desktop app, which has the server's url and no type. Claude Code reads an entry with no type as a server it should start on the laptop, and the entry names no program to start, so Claude Code skips it and reports: MCP server "jira" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. sse and ws in the message are two other kinds of network connection that Claude Code accepts for a remote server, and the team's remote servers use http. With the type added, the file looks like this:
{
"mcpServers": {The file holds one list, mcpServers, with one entry for each server. The name of each entry is the name Claude sees in mcp__jira__….
"jira": {
"type": "http",
"url": "https://mcp.atlassian.com/v2/mcp"
}The jira server is remote and is reached over HTTP at Atlassian's address. The line "type": "http" is the one Atlassian's snippet left out.
}
}The ends of the list and of the file.
She removes her local copy with claude mcp remove jira --scope local, because while it exists, her laptop uses it in place of the team's entry. She commits the file and pushes it to the team's . The first time each engineer starts Claude Code in the repository after pulling, Claude Code asks them to approve the new server, because anyone who can commit to the repository could otherwise add a server that starts on every engineer's laptop without their knowledge. Then each of them signs in to Atlassian through /mcp.
Project scope
Claude Code reads servers from the repository's .mcp.json and from each engineer's own ~/.claude.json. The tech lead runs claude mcp add with no scope, so the Jira entry goes into her ~/.claude.json under payments-platform, and Claude on her laptop can read PAY-2817.
A new joiner clones payments-platform on Monday. He gets the repository's files, and the tech lead's ~/.claude.json stays on her laptop.
He asks Claude to read PAY-2817. Claude has only its built-in tools, because the Jira server is set up on the tech lead's laptop alone.
The tech lead removes her local entry and writes the Jira server into .mcp.json at the repository root, with "type": "http". The Jira server itself does not change. Only the file that holds its entry changes, and the entry holds only the server's type and address.
She commits and pushes the file, and every engineer gets .mcp.json with their next clone or pull. Claude Code on each laptop lists the Jira server as waiting for approval.
The new joiner starts Claude Code, approves the server once and signs in to Atlassian with his own account. Claude on his laptop now has the Jira tools and can read PAY-2817, and the other engineers approve the server the same way.
A server's entry reaches every engineer only when it is in .mcp.json, committed to the repository. An entry in one engineer's ~/.claude.json serves that engineer alone.
Project scope: .mcp.json reaches every engineer through git
On the tech lead's laptop, claude mcp add wrote the jira entry into her ~/.claude.json, in the section for the payments-platform folder. After she signs in to Atlassian through /mcp, claude mcp list shows the server connected.
The new joiner runs git clone. His laptop receives everything in the repository, which has no .mcp.json, and claude mcp list on his laptop reports no servers.
The tech lead creates .mcp.json at the repository root and pastes the snippet Atlassian publishes for Claude's desktop app, which has a url and no type. Claude Code skips the entry and reports an error that asks for a type, such as http.
She adds "type": "http" and removes her local entry with claude mcp remove jira --scope local, so the jira entry now exists only in .mcp.json.
She commits and pushes the file. The new joiner and the other 38 engineers run git pull, and .mcp.json arrives on every laptop.
The new joiner's claude mcp list shows the server waiting for approval. He starts Claude Code and approves the server, then signs in to Atlassian through /mcp, and the status changes to connected. Every other laptop goes through the same steps.
The entry reached every laptop once it was in a committed file inside the repository, and each engineer still approved the server and signed in with their own account.
Claude Code asks for approval of a project server only in an interactive session, where an engineer is typing at the keyboard. A run, which answers one prompt from a script with nobody at the keyboard, and an agent built on the load the servers in .mcp.json without asking.
If one server name is in more than one scope, the local entry wins over the project entry, which wins over the user entry. Claude Code uses the whole winning entry and ignores the others, even for settings the winning entry leaves out.
Claude Code reads server entries only from files such as .mcp.json and ~/.claude.json. A list of servers written in CLAUDE.md, or a file such as .claude/mcp.yaml, does nothing. An exam option that puts server entries in such a file is wrong.
A GitHub token typed into .mcp.json reaches every clone and the git history.
GitHub's server can sign in through the browser or use a personal access token, a long secret string that lets the server act on GitHub as the person it belongs to. When GitHub's server runs on a laptop and signs in through the browser, it keeps the sign-in in memory only, so every new start of the server asks for a browser sign-in again. Claude Code stores the Atlassian sign-in itself, so once an engineer has signed in, jira keeps working in later sessions and in scripts. The team also runs Claude Code from scripts, where nobody is at a browser, so it runs GitHub's server with a token. The tech lead adds github to .mcp.json with her own token typed into it, and commits the file:
"github": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"],Start GitHub's own server on the engineer's laptop with , a program that runs packaged software the same way on every laptop. ghcr.io/github/github-mcp-server is GitHub's packaged server. run -i --rm starts it, keeps its input open for Claude Code's messages, and has Docker delete this run's copy of the server when it stops. -e GITHUB_PERSONAL_ACCESS_TOKEN passes in the token under the name GitHub's server reads. An entry with a command and no type is a server: Claude Code starts it as a program and exchanges messages with it through that program's input and output.
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_11A…"
}
}env sets GITHUB_PERSONAL_ACCESS_TOKEN for the program Claude Code starts, and Docker's -e passes that value into GitHub's packaged server. Here the value is the tech lead's own token, written into the file. It is shortened on this page.
The file is now in every clone, so her token is on 40 laptops, and anyone with a clone can use it to act on GitHub as her. Changing the file later does not remove the token, because git keeps every committed version of every file in the repository's .
Environment variable expansion keeps the token out of the file.
An is a named value set on one engineer's machine, such as GITHUB_TOKEN, which programs read when they start. lets .mcp.json name a variable instead of holding its value: the team writes ${GITHUB_TOKEN} in the file, and when Claude Code starts the server it replaces that text with the engineer's own value. In the github entry the line becomes "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}". The name on the left is the one GitHub's server reads, and the value on the right comes from the engineer's own GITHUB_TOKEN. ${VAR:-default} uses the default when the variable is not set, so ${LEDGER_MCP_URL:-https://ledger.example} gives the usual address to anyone who has not set LEDGER_MCP_URL. Expansion works in five fields of an entry, command, args, env, url and headers, and the team's final file below uses it in env, url and headers.
The fix has three parts. The tech lead the leaked token on GitHub, so the copies in every clone and in the history stop working. She replaces the token in .mcp.json with ${GITHUB_TOKEN} and commits again. Each engineer creates a personal token on GitHub and sets GITHUB_TOKEN on their own laptop, for example with this line in the terminal:
export GITHUB_TOKEN=github_pat_11B…Set the variable GITHUB_TOKEN to this engineer's own token for every program started from this terminal, including Claude Code. The token is shortened on this page.
An engineer who forgets to set the variable still gets the server: Claude Code starts it with the text ${GITHUB_TOKEN} unchanged, and claude mcp list and /mcp show a warning that names the variable. GitHub then refuses the text ${GITHUB_TOKEN} as a token.
One wrong fix adds .mcp.json to , the list of files git should not start tracking. Git keeps tracking a file that is already committed, so the team would also have to run git rm --cached .mcp.json, which stops git tracking the file and leaves the file on the laptop. The token would still be in every earlier commit and would still need revoking, and every clone made after that change would have no .mcp.json, so a new joiner would again start with no jira server.
Environment variable expansion
The tech lead adds the GitHub server to .mcp.json with her own GitHub token written into the entry, and commits it. Every clone and pull copies the token to the other 39 laptops, and after each engineer approves the server, Claude Code there starts it with her token.
Later a teammate changes the Jira entry and commits. Git keeps every earlier version, so her token is now in two commits, and it will stay in the history even after the file changes.
The tech lead revokes her token on GitHub. Every copy of it, in the file, in the history and on every laptop, stops working, and every other token GitHub has issued keeps working.
She replaces the token in .mcp.json with ${GITHUB_TOKEN} and commits. Each engineer creates a personal token on GitHub and sets it as GITHUB_TOKEN on their own laptop.
When the new joiner starts Claude Code, it replaces ${GITHUB_TOKEN} with his own token and starts the GitHub server. On a laptop where GITHUB_TOKEN is not set, the server starts with the text ${GITHUB_TOKEN} unchanged, and Claude Code shows a warning that names the variable.
The committed file names a variable and holds no token. Each engineer's token stays on their own laptop, and the token that was committed has been revoked, because git history keeps it.
Environment variable expansion: each laptop supplies its own token
The pull request “add github MCP server” adds the github entry to .mcp.json with the tech lead's token in its env field. It is merged, and the commit joins the history of payments-platform.
Every engineer runs git pull, and the token arrives on the other 39 laptops. A later commit changes the file, and the earlier commit still holds the token.
The tech lead revokes her token on GitHub, so every copy, including the one in the history, stops working. A second pull request then replaces the token with ${GITHUB_TOKEN}.
The tech lead sets GITHUB_TOKEN to her new personal token and starts Claude Code. Claude Code puts her value in place of ${GITHUB_TOKEN} when it starts the server, and claude mcp list shows github connected.
Another engineer has not set GITHUB_TOKEN. Claude Code still starts the server, with the text ${GITHUB_TOKEN} unchanged, and claude mcp list shows a warning that names the variable.
One wrong fix adds .mcp.json to .gitignore and stops git tracking it with git rm --cached. The token stays in the earlier commits and still needs revoking, and a laptop that clones the repository after that change gets no .mcp.json, so claude mcp list there reports no servers.
The committed file now names GITHUB_TOKEN and holds no token, and each laptop supplies its own value when Claude Code starts the server.
This is the team's .mcp.json once all three servers are in it:
{
"mcpServers": {
"jira": {
"type": "http",
"url": "https://mcp.atlassian.com/v2/mcp"
},Atlassian's remote Jira server. It holds no token, because each engineer signs in to Atlassian through /mcp.
"github": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"],GitHub's server, started on each laptop with Docker.
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
},GitHub's server reads only the name GITHUB_PERSONAL_ACCESS_TOKEN. Each engineer keeps their token under the shorter name GITHUB_TOKEN, and this line copies one into the other: when Claude Code starts the server, it replaces ${GITHUB_TOKEN} with the value of GITHUB_TOKEN on that engineer's laptop.
"ledger": {
"type": "http",
"url":
"${LEDGER_MCP_URL:-https://ledger.example}/mcp",The team's own server. If an engineer has set LEDGER_MCP_URL, its value is used, for example a test copy of the server; if not, the default address after :- is used. The address here is a placeholder.
"headers": {
"Authorization": "Bearer ${LEDGER_TOKEN}"
}
}
}
}headers are labelled lines sent with every request to the ledger server. The Authorization line carries the engineer's own LEDGER_TOKEN, filled in from their environment, and Bearer is the word that marks the value as a token. The payments platform team issues each engineer's ledger token.
Part 3: A personal server goes in ~/.claude.json, and Claude uses every server's tools in one session
A personal server in .mcp.json fails to start on every teammate's laptop.
A refunds engineer is building upi-mandate-sim, an that imitates a bank's replies when a customer sets up , which banks call a mandate, so that she can test refund code without a real bank. The server is a file on her laptop that runs, and its one tool, create_mandate, returns a bank's reply to a new mandate. She adds the server to the team's next to the other three:
"upi-mandate-sim": {
"command": "node",A server Claude Code starts on the laptop by running node.
"args": [
"/Users/refunds-dev/code/upi-mandate-sim/server.js"
]
}The file node runs. This points into her own , so it exists only on her laptop.
After the next pull, every teammate's Claude Code asks them to approve upi-mandate-sim. For anyone who approves it, Claude Code tries to start the server from that path on their own laptop, and the server fails to start, because the file does not exist there. Every change she makes to its entry, such as a new argument, would also reach the other 39 engineers through .
User scope keeps a personal server on one laptop and in every project.
puts a server's entry at the top level of the engineer's own . The server then loads in every project she opens on her laptop, and on nobody else's laptop. The exam guide gives user scope for personal and experimental servers.
She removes the entry from .mcp.json and that change. Her first try at a personal entry is claude mcp add upi-mandate-sim -- node with the path to her file and no --scope, which writes the entry into her ~/.claude.json under the payments-platform folder:
{
"projects": {
"/Users/refunds-dev/code/payments-platform": {Claude Code's section for one project, filed under that project's folder on her laptop.
"mcpServers": {
"upi-mandate-sim": {
"command": "node",
"args": ["…/upi-mandate-sim/server.js"]
}
}
}
}
}Her server's entry inside that project's section, with the path to her file shortened on this page. This is : the server loads only when she works in payments-platform.
The next day she opens another , refund-tools, and her simulator is not there, because a local entry loads in one project only. A question that says an engineer wants a server “in all my projects” is asking for user scope. She removes the local entry with claude mcp remove upi-mandate-sim --scope local and adds the server again with --scope user:
claude mcp add --scope user upi-mandate-sim \Add a server named upi-mandate-sim to her own ~/.claude.json, for all her projects.
-- node /Users/refunds-dev/code/upi-mandate-sim/server.jsThe two dashes end Claude Code's own options. Everything after them is the command that starts her server.
The command writes an entry like this at the top level of her ~/.claude.json, outside every project's section:
{
"mcpServers": {
"upi-mandate-sim": {
"command": "node",
"args": [
"/Users/refunds-dev/code/upi-mandate-sim/server.js"
]
}
}
}An mcpServers list at the top level of the file, outside any project's section, which is what makes it load in every project she opens.
In payments-platform, her Claude Code reads both files, connects to all four servers and sends each one the same request. All their tools are available in one , including her simulator's tool under the name mcp__upi-mandate-sim__create_mandate. Claude never switches between servers or needs a separate session for each one, and in a single task it can read a Jira ticket, search the ledger and open a .
User scope
A refunds engineer is building upi-mandate-sim, an MCP server whose code is in a folder under /Users/refunds-dev/code on her laptop, and adds it to the team's .mcp.json.
A teammate pulls the change. His Claude Code asks him to approve upi-mandate-sim, he approves it, and Claude Code tries to start the server from the same path on his laptop. The server fails to start, because the file does not exist there.
She removes the entry from .mcp.json and commits, and after the next pull her teammates' Claude Code no longer lists the server. She adds it again with no scope, so the entry goes into her own ~/.claude.json for payments-platform only, which is local scope.
She opens another repository, refund-tools, whose .mcp.json lists no servers. Claude Code there loads none of the team's three servers, and it does not load her simulator either, because a local entry loads in one project only.
She adds the server again with --scope user, so the entry moves to the top level of her ~/.claude.json. Claude Code in refund-tools now loads her simulator, and so will every other project she opens on her laptop.
Back in payments-platform, Claude Code loads the three project servers from .mcp.json and her user server from ~/.claude.json, and Claude can use tools from all four in one session.
User scope: her server loads in every project on her laptop
A pull request adds upi-mandate-sim to .mcp.json with a path to a file on her laptop, and it is merged. A teammate pulls, starts Claude Code and approves the new server, and it fails to connect, because his laptop has no such file.
A second pull request removes the entry. In payments-platform she runs claude mcp add with no scope, and the entry goes into her ~/.claude.json under the payments-platform folder.
In her terminal in another repository, refund-tools, claude mcp list shows no servers, because the local entry belongs to payments-platform.
She removes the local entry and runs claude mcp add --scope user. The entry moves to the top level of her ~/.claude.json.
In refund-tools, claude mcp list now shows upi-mandate-sim connected.
In payments-platform, claude mcp list shows four servers connected: jira, github and ledger from .mcp.json, and upi-mandate-sim from her ~/.claude.json. The next request carries tools from all four.
Her entry is at the top level of the file in her home folder, so it loads in every project she opens on her laptop and on nobody else's, and in payments-platform it works beside the team's three servers in the same session.
An agent built on the Agent SDK uses the same servers in one run.
The team also runs a nightly agent built on the . At 2 a.m., on one of the team's build machines, it searches the ledger for refunds that stayed in processing overnight and opens a draft pull request for the on-call engineer to review. The agent loads the servers in .mcp.json just as Claude Code does. The SDK calls the groups of settings files it reads , and the repository's own files, .mcp.json among them, are the project source. The nightly agent's options do not mention settingSources, so the SDK reads every source, including project. Options that list settingSources and leave project out would leave the team's servers out of the run.
When a run starts, and before Claude does any work, the SDK gives the agent's program a first message, the . It lists every tool the agent has, including the tools of each server that has connected by then, and a status for each server, such as connected, pending, failed or needs-auth. This is a shortened init message from the nightly agent:
{
"type": "system",
"subtype": "init",The first message of a run, which the SDK marks as a system message of the kind init.
"tools": ["Read", "Edit", "Bash",
"mcp__github__create_pull_request",
"mcp__github__pull_request_read"],Every tool the agent can use. The MCP tools are the ones whose names start with mcp__, here two of the github server's tools.
"mcp_servers": [
{ "name": "jira", "status": "needs-auth" },
{ "name": "github", "status": "connected" },
{ "name": "ledger", "status": "pending" }
]
}One status for each server. Nobody has signed in to Atlassian on the build machine, so jira is marked needs-auth and the run has none of its tools. The nightly task uses only the ledger and GitHub, so the run goes on without Jira. github has connected with the set on that machine, so its tools are in the list above. ledger is still connecting, so none of its tools are listed yet.
Before Claude Code or an agent runs a tool, it can stop and ask a person whether to run it; that question is a . Nobody is awake at 2 a.m. to answer one, so the agent's options list the tools it may run without a prompt in (allowed_tools in Python). The entry mcp__github__* matches every tool name that starts with mcp__github__, so it covers every tool of the github server:
options: {
allowedTools: ["mcp__github__*",
"mcp__ledger__*"],
}Let every tool of the github and ledger servers run without a permission prompt. In Python the option is written allowed_tools.
A wildcard approves every tool the server offers, both the tools that read data and the tools that change it. The nightly agent needs only mcp__ledger__search_ledger and mcp__github__create_pull_request, so the team could list those two names instead, and every other tool would then need a permission prompt before it runs.
MCP servers in an agent: the init message gives each server's status
The nightly agent starts at 2 a.m. and loads the servers in .mcp.json. Its init message says github has connected and ledger is still connecting, and jira needs a sign-in to Atlassian that nobody has made on this machine. The tool list has the built-in tools and GitHub's tools, and no Jira tools.
A few seconds later the ledger server finishes connecting, and its tool search_ledger is added to the agent's tools for this run, below the tools the init message listed. The init message did not include it, because the server was still connecting when the message was sent.
Claude asks for mcp__ledger__search_ledger and finds two refunds stuck in processing, then asks for mcp__github__create_pull_request to open a draft pull request. Both names match entries in allowedTools, so both calls run without a permission prompt, and the agent uses tools from two servers in one run.
The agent loaded the team's servers from .mcp.json, reported each server's status in its init message, and used tools from two servers in one run without a permission prompt.
Part 4: Claude uses a team server when it can tell what the server offers
Claude chooses a tool by reading its name and description.
Claude chooses between its by reading each tool's name and . The description of , the that searches the text of files, says plainly that it searches the contents of files, and searching files answers many questions about a . A tool whose description is vague gives Claude no reason to choose it, even when it is the only tool that reaches the data a question needs.
Claude searches the repository with Grep and never calls the ledger tool.
The ledger has one tool, search_ledger, and its description is one line: “Search ledger.” An engineer asks Claude Code, “Why is refund rfnd_2817 stuck in processing?” Claude runs Grep for rfnd_2817 across payments-platform. It finds the ID in a and in a sample log file kept for tests, and replies that it cannot find the refund. The refund's history is in the , which is a database, and Grep searches only files.
“Search ledger.” does not say what the ledger holds, what the tool accepts or what it returns, so Claude has no reason to prefer it. The exam guide's fix is to expand the MCP tool's description so that it explains the tool's capabilities and outputs in detail, which stops Claude from preferring a built-in tool such as Grep over a more capable MCP tool. Chapter 13 covers how to write a tool description in general.
MCP tool descriptions
An engineer asks, “Why is refund rfnd_2817 stuck in processing?” Claude reads the descriptions of its tools. Grep's description says in several lines what it searches, what it takes and what it returns, and the description of search_ledger says only “Search ledger.”
Claude asks for Grep. Claude Code runs the search and finds the refund ID only in a test fixture and in a sample log file kept for tests. The ledger is a database outside the repository, and Grep searches only files.
Claude reads the two matches, finds no record of the refund in them, and replies, “I can't find this refund.” The ledger server, which holds the record, was never called.
The team rewrites the description of search_ledger. Its first words say that the tool searches Razorpay's live payments ledger, which is not in the code repository, and the rest says what the tool accepts and returns.
The engineer asks again. Claude reads both descriptions and asks for search_ledger. Claude Code passes the call to the ledger server, which returns three events for rfnd_2817, and Claude reports that the bank sent the refund back, which left it in processing.
Claude chooses a tool by reading its description, so it asked for search_ledger only after the description said what the ledger holds and when to search it.
The team's ledger server is written with the official MCP library for Python, which uses the 's name as the tool's name and the text between the triple quotes """ as its description. The new description gives amounts in , hundredths of a rupee. This is search_ledger before and after the rewrite:
@mcp.tool()
def search_ledger(ref: str) -> list[dict]:
"""Search ledger."""The first version. @mcp.tool() publishes the function as a tool, ref is the one input, and -> list[dict] means it returns a list of records. The description Claude reads is two words long.
@mcp.tool()
def search_ledger(ref: str) -> list[dict]:The same tool, with the same name and input.
"""Searches Razorpay's live payments ledger, which
is not in the code repository, for one refund, payment
or bank transfer.What the tool searches, and that this data is not in the repository. These words come first, as Anthropic's documentation advises, because Claude Code can cut a long description and tool search reads only its first 4,096 characters.
Accepts a refund ID (rfnd_...), a
payment ID (pay_...) or a bank reference number.
Returns every ledger event for that item with its
status, timestamp and amount in paise, newest first.What it accepts and what it returns, including the unit of the amounts, which is paise.
Use this for any
question about what happened to a real payment or
refund; searching files with Grep finds only code and
test fixtures, never ledger rows."""When to use it, and why Grep cannot answer the same question.
MCP tool descriptions: Claude reads each tool's description before it chooses (illustrative ledger values)
The engineer asks, “Why is refund rfnd_2817 stuck in processing?” The request goes to Claude with every tool in its list, and the ledger tool's description is only “Search ledger.”
Claude asks for Grep with rfnd_2817. Claude Code searches the files of payments-platform and finds two lines, in a test fixture and in a sample log kept for tests. The result goes back to Claude, and the ledger server is never called.
Claude replies that it cannot find this refund in the repository.
The team rewrites the description of search_ledger. It now says what the tool searches, what it accepts, what it returns and when to use it instead of searching files, with the most important words first.
The engineer asks the same question, and this time the request carries the new description.
Claude asks for mcp__ledger__search_ledger with rfnd_2817. Claude Code sends the call to the ledger server, and three ledger events go back to Claude.
Claude answers that the bank sent the refund back at 14:05 with reversal code RV07 and that the refund has stayed in processing since then.
Next the engineer asks where the code handles refunds that banks send back. Claude asks for Grep, and Claude Code finds services/refunds/src/reversals.ts. Code questions still go to Grep, so the team keeps both tools.
Claude chose search_ledger once its description said what the tool reaches and when to use it, and it still asked for Grep for a question about the code.
Three other fixes look tempting, and each one leaves the one-line description in place and costs the team something else. Removing Grep takes away the tool Claude needs when a question is about the code itself, such as finding the code that handles refunds a bank sends back with a . A line in that says “always use the ledger server” leaves the description saying nothing, so Claude still cannot tell what the tool returns. A that blocks Grep and points Claude at the ledger tool (a PreToolUse hook, which runs before each tool call, as chapter 2 showed) adds code to work around a description the team can rewrite, and so does a keyword router, which is code that sends a question to a tool when the question contains certain words.
With only tools, Claude makes eight calls to find one column.
A is read-only content that an MCP server offers at an , such as one table's at schema://refund_events or the team's list of , its written guides for fixing known problems, at runbooks://index. At first the ledger server offers no resources, only tools.
The next task is “Add the bank's reversal code to the refunds report.” After Part 1 the team added two more tools to the ledger server, list_tables and describe_table, so it now has three. Claude does not know which table holds the code, so it lists the tables, describes five of them and searches twice before it finds the column bank_reversal_code in the table refund_events. That is eight calls. Each call is a new request to Claude, and every result stays in the , so the task is slower and uses more tokens for the rest of the .
Resources give Claude a catalogue of the ledger's tables to read.
Each resource is listed with its address, a name and, when the server gives one, a description. Claude Code gives Claude two built-in tools for resources, ListMcpResourcesTool to list a server's resources and ReadMcpResourceTool to read one, and an engineer can attach a resource to a prompt by typing @. The exam guide puts the split this way: “resources for content catalogs, tools for actions”.
The team registers one resource for each of the ledger's eight tables, each with a description of what the table holds, and one for the runbook index. list_tables returned eight bare table names, so Claude had to describe one table after another. Listing the resources returns nine entries, the eight tables and the runbook index, each with a line on what it holds. The line for schema://refund_events is “Every status change of a refund, including bank reversal codes.” Claude still asks Claude Code to list the resources and to read one, and those two calls lead straight to the right table, so Claude makes no exploratory calls: it lists the ledger's resources once, reads schema://refund_events, and has the column in two calls.
A resource differs from a tool's result in one more way. A resource is fixed content that exists before anyone asks for it, so Claude Code can list it for the engineer in the @ menu and attach it before Claude starts. If the engineer types @ledger:schema://refund_events in the prompt, Claude has the schema with the task and makes no call to find it. A tool's result exists only after Claude calls the tool, so even a list_tables that returned a line on each table would still cost Claude a call. The exam guide's rule is to offer content that Claude reads as resources and to keep tools for actions.
@mcp.resource(
"schema://refund_events",
description="Every status change of a refund, "
"including bank reversal codes.",
)
def refund_events() -> str:
return describe("refund_events")A resource at the address schema://refund_events. Its description is the line Claude reads in the resource list; Python joins the two quoted pieces into one line. Reading the resource returns the table's columns. describe is the team's own function.
@mcp.resource(
"schema://daily_batches",
description="Each day's batches of payments "
"sent to banks.",
)
def daily_batches() -> str:
return describe("daily_batches")
# one like this for each of the other six tablesThe same for the daily_batches table. The team writes one like this for each of the other six tables, so the resource list has one entry for every table.
@mcp.resource(
"runbooks://index",
description="The team's runbooks, "
"with one line on each.",
)
def runbook_index() -> str:
return load_runbook_index()One more resource, the list of the team's runbooks, with its own description.
Each of these resources returns content that exists ahead of time and can be read at a fixed address. A lookup that needs a query, such as search_ledger with a refund ID, stays a tool, and so does anything that changes data, such as cancelling a payment. The team keeps search_ledger and removes list_tables and describe_table, because the schema resources now give Claude the same content.
MCP resources
An engineer asks Claude to add the bank's reversal code to the refunds report. The ledger server offers three tools, list_tables, describe_table and search_ledger. Claude's first call is list_tables, and Claude Code brings back eight table names.
Claude does not know which table holds the code. Its second call describes refunds, which has nine columns, and its third describes bank_reversals, which has six. Neither has the code.
Calls four to six search the ledger once and describe daily_batches and payouts, and none of the results has the code either.
Call seven searches the ledger again, and call eight describes refund_events, whose columns include bank_reversal_code. Claude needed eight calls to find one column.
The team adds resources to the ledger server: one schema for each table, each with a line on what the table holds. It removes list_tables and describe_table and keeps search_ledger, and Claude Code gives Claude its two tools for listing and reading resources.
With the same task, Claude's first call lists the ledger's resources, and the list comes back with a line on each table. Its second call reads the schema of refund_events, which shows bank_reversal_code.
In a new task, the engineer attaches the refund_events schema to the prompt by typing @. Claude Code gives Claude the schema with the task, and Claude has the column before it makes any call.
With resources, Claude reads what data the ledger holds from a list with a line on each table, and tools such as search_ledger stay for lookups and for actions that change data.
MCP resources: the ledger server lists what each table holds (illustrative calls)
The engineer asks Claude to add the bank's reversal code to the refunds report. The ledger server offers only tools, and Claude Code sends the request to Claude.
Claude's first call is mcp__ledger__list_tables, and the names of eight tables go back to Claude.
Claude does not know which table holds the code, so calls two to eight ask for describe_table five times and search_ledger twice. The eighth call, describe_table on refund_events, returns the column bank_reversal_code.
The team adds resources to the ledger server: one for each table, such as schema://refund_events, each with a line on what it holds, and runbooks://index. It removes list_tables and describe_table, Claude Code adds its two tools for resources, and Claude starts the task again.
Claude's first call is ListMcpResourcesTool on the ledger server. The list goes back with a line on each table, and the line for schema://refund_events says it holds every status change of a refund, including bank reversal codes.
Its second call is ReadMcpResourceTool with schema://refund_events, which shows the column bank_reversal_code, and Claude can now write the report's query.
Next time the engineer types @ and picks ledger:schema://refund_events from the menu. Claude Code attaches the schema to the request before it goes to Claude, so Claude makes no call to find the column.
The resource list carried a line on each table, so Claude went straight to the table that holds bank_reversal_code and found the column in two calls instead of eight, and with the schema attached it made no call at all to find the column.
The exam guide gives issue summaries, documentation hierarchies and database schemas as examples of content that a server should offer as resources.
Part 5: Check yourself
Choose what goes in the team's .mcp.json.
The payments platform team is cleaning up its MCP setup. Select every item that belongs in payments-platform/.mcp.json, the file every engineer gets from git, then check.
Select at least one item first.
Claude keeps choosing Grep over the ledger tool.
Your team's Claude Code setup includes a custom MCP server for the company's internal payments ledger. Its tool search_ledger has the description “Search ledger.” When engineers ask why a ₹1,499 refund is stuck, Claude usually runs Grep across the repository, finds only test fixtures, and reports that it cannot find the refund. What is the most effective first step?
Razorpay appears in this chapter only to explain how Claude Code and Claude work. Razorpay has no connection with these tutorials, and the code, systems, numbers and events in this chapter were written for the lesson. They do not describe how Razorpay works, and Razorpay does not use this code.