Skip to content
AI agents & MCP

MCP Tools Explained: Permissions, Scopes and Safe Writes

By Sebastiaan Jansen · · 17 min read

MCP tools are named functions that a server offers to an AI client. People comparing mcp tools usually want to settle two lists: the calls a model may make, and the calls the host must refuse. The model can ask for a call, but the host decides whether it runs, with which arguments, and whether the result may change stored data. Permissions, scopes and safe-write checks turn that request into something a team can allow.

Without those checks, a tool list is just a menu of things the model can ask for. With them, you can write down a contract: this client may read these records, may write these fields, and must stop if the record changed after it was read.

What MCP tools are

An MCP server publishes three kinds of capability: resources (data the client can read), prompts (reusable prompt templates) and tools (functions the model can invoke). Each tool has a name, a description and an input schema, usually JSON Schema. The client sends that catalogue to the model, the model returns a tool name and arguments, and the client runs the call and hands back the result.

The model never opens your database, your git remote or your ticket board. It proposes a call, and something in the host process has to accept the proposal, check it and carry it out. Policy belongs in the host, because the model will follow whatever the tool description makes sound reasonable.

Teams that connect an MCP server should be able to say in one sentence what each tool is allowed to change. "This client may read tickets in the current cycle and may move a ticket from in_progress to in_review when the version matches" is a sentence you can test. "The agent can help with project work" is not.

A resource is data the client may attach to context. A tool is a function with arguments and a result. If opening a resource changes a record, treat it as a tool. A prompt can tell the model which tool to prefer, but it can't stop a later message from asking for a different one.

How MCP tools declare what they can do

The tool definition is the first permission boundary, though it doesn't enforce anything on its own. Four fields do most of the work.

Name and description

The name should carry the verb and the object: get_ticket, update_ticket_stage, create_pull_request. Names like run, do_action or manage leave the model guessing. The description should state side effects in plain language, for example "Reads one ticket. Does not write." If the description hides a write, a tool that looks read-only will eventually ship a change.

Name the object, the mutation, and what the tool refuses. "Updates a ticket stage. Requires expected_version. Rejects any move that skips in_review." is enough. "Helps manage tickets efficiently" invites the model to try things the server should never allow.

A name narrower than the implementation is a second mistake. An add_comment that also reassigns the ticket and emails watchers is three tools under one name, so split them. A reviewer confirming "add a comment" should not also be confirming a notification and an owner change.

Input schema

The schema lists required fields, types and enums, and an enum for stage works as a permission. If the only allowed values are triage, ready and in_progress, the model can ask for released all it likes and the server will refuse it. A free-form string for a status, a path or a shell command hands the real decision back to the model.

Prefer required fields over optional bags of properties. An optional force: true will get set the moment a tool result says the ordinary path failed. If you need a bypass, make it a separate tool with a stricter scope instead of a boolean on the everyday tool.

Constrain identifiers. A ticket id pattern, a repository slug from a fixed list and a maximum length on free text all remove arguments the model might invent. A reason field with no length limit is somewhere to paste a customer record into a log line, so cap it. Reject unknown fields too. If the server ignores notify: true today and honors it next month, every stored call turns into a different operation.

Output shape

Return the smallest record the next step needs. The model will quote whatever it receives, including secrets and unrelated customer fields. If you would reject the endpoint in an API review, reject the tool too.

A get-ticket tool that returns the full row will include internal notes and billing identifiers, and the model will paste them into a pull request body because they were in context. Return id, title, stage, version, assignee and the acceptance line.

Errors are output as well. Return a stable code: stale_version, missing_scope, illegal_transition, not_found. "Something went wrong, try again" invites a retry of the same write. Include the current version and the allowed next stages so the model can read again or stop.

Where MCP security is enforced

Most people reading up on mcp security have already seen the protocol diagram and want to know who can stop a bad call. The protocol provides the hooks. The host has to use them.

  • Show the pending call and its arguments before it runs whenever the tool can write, send, delete or spend money.
  • Bind the call to a user or service identity, and refuse it if that identity is missing.
  • Allow or deny by tool name and by argument pattern, instead of one on/off switch for the whole server.
  • Record the request, the decision and the result so a reviewer can reconstruct what changed.

A prompt that says "never delete production" controls nothing. A later message, a poisoned page in a resource, or a tool result claiming the delete is required can all talk the model out of it. A host rule that refuses delete_ticket unless the caller has an admin role keeps working when the prompt changes.

Pin third-party servers to a version and alert when a new tool shows up, since every new tool is a new permission. A local stdio server trusts the OS user, while a remote server trusts the client identity. Once a hosted agent can reach that server, a token from someone's laptop has turned into a shared credential.

Before you trust the diagram, walk a write through the host. The model emits a tool name and a JSON argument object. The host looks the name up in the pinned catalogue and stops if it isn't there. If the tool can write, the host shows arguments a person can check: ticket id, version, from stage, to stage. The person approves or rejects, and only then does the host attach the identity and send the call. The server checks the token, the scope, the schema and the version. Log the decision even when the person rejects the call. A dialog that says "Update ticket?" without the id, the version and the stage change trains people to click through.

Allowing create_pull_request for every repository is a different policy from allowing it only when repo is billing-export and base is main. Put the slug check in the host if you can't change the server, and in the server as well if you own it. A check that lives only in a prompt doesn't count.

A local stdio server runs as the OS user, so a read_file tool with a free-form path can propose a credentials file sitting in the home directory. Constrain paths to the workspace and refuse paths that escape it. When a pinned server adds a tool, treat the update as a permissions change. Read the new name, description and schema before you accept the version. A patch that adds export_workspace has opened a new way for data to leave.

Scopes, and what MCP OAuth actually grants

For remote servers, mcp oauth is the pattern the specification points to: the client gets a token through OAuth, and the server only accepts calls when that token is valid for the resource. The token tells the server who the client is and which scopes it holds. It says nothing about whether a given argument is a good idea.

Scopes should map to tools, not to a vendor's whole product.

Scope Tools it may call Typical approval
tickets:read get ticket, list cycle, read roadmap counts Default for planners and reviewers
tickets:write create ticket, move stage, add a comment Named people, or an agent with a per-run grant
repo:read read files, list branches, show diff Default for coding agents in a workspace
repo:write push a branch, open a pull request Granted per repository, never as a blanket org scope
admin change roles, delete records, edit workflow rules Humans only, with a second confirmation

The server checks the token first, then the tool, then the arguments. A token with tickets:read that calls update_ticket_stage fails even when the payload is well formed. If your identity provider only offers a coarse scope, enforce the tool allow list in the server anyway, and prefer tokens that expire with the agent session. The protocol site documents authorization: Model Context Protocol. An expired token, a wrong audience, a missing scope or revoked consent should each fail closed.

Check the audience. A token minted for a documentation server must not be accepted by the ticket server, even when both use the same identity provider and the scope strings look alike. The resource indicator ties the token to this server. Skip that check and a client can replay a low-risk token against a high-risk server.

Keep grants short. When an agent session ends, its write scope should end with it. A refresh token in a shared CI secret outlives the review that approved the original run. For a background agent, issue a token for that run, bind it to the repository and the ticket, and let it expire when the run ends.

Consent screens should name the tools. "Allow read of tickets in this workspace, and write of stage changes you confirm" is a question a person can answer. If the provider can only show a coarse scope, repeat the finer rule in the server's own confirmation step.

When someone leaves the team, revoking the grant should make the next call fail before any tool runs. Test that path. A server that caches the scope decision until restart will keep honoring a grant you think is gone.

Keep the access token out of tool arguments and tool results. The host attaches it. A tool that returns debug headers will leak the credential into the transcript.

Safe writes

A write is safe when a second reader can see what changed, and what would have happened if the record had moved underneath the caller. Reads can be retried. Writes race, because a person can edit the same record between two agent turns.

Read, then write against a version

  1. Read the record and keep the version the server returned. That might be a row version, an etag, a commit SHA or an updated-at timestamp the server advances.
  2. Decide the change based on that snapshot.
  3. Send the write along with the version you read.
  4. If the server says the version is stale, stop and read again. Do not retry the same patch.

A bare "set status to done" with no version will overwrite a newer edit that moved the work back to review.

The server has to advance that version on every successful write, including writes from the UI. A timestamp the client sends is not a version, and neither is a version the client may leave out. Return the new version so the next call doesn't reuse the old one.

Compare the full precondition. Stage moves should include from_stage and expected_version, and the server should evaluate "version is 17 and stage is still in_progress" as one check.

Separate propose from apply

When an operation is hard to undo, split the tool in two. propose_stage_change returns the diff and the version. apply_stage_change requires that proposal id, the same version, and an actor who is allowed to apply. The model can prepare the first call. The second waits for a person, or for a policy that auto-approves only a narrow move, such as ready to in_progress inside the caller's own cycle. Store an idempotency key with the result so a retry after a timeout doesn't write twice.

The proposal should include the ticket id, the version that was read, both stages, the reason and the actor. Give it an expiry: a proposal from Monday should not apply on Friday to a ticket that has since been split and moved. If the version changed, apply fails the same way a direct write would.

Pick the idempotency key in the host before the call, and send the same key on retry. If the model invents a new key on each attempt, each attempt is a new write. On a duplicate key, return the original result, including when the first attempt succeeded and the response was lost.

If a tool needs two permissions, it should fail when either one is missing. Don't open a pull request with a made-up body because the ticket read failed. On every write, log the actor, the tool name, the version read, the version written and the time.

If the server moves the stage and then fails to post the comment, it should say so and include the new version. A timeout with no body is how a client ends up retrying and double-posting. Keep the important mutation in one transaction, and put optional side effects in a follow-up tool.

A worked example: moving one ticket

A coding agent is working on a ticket titled "Add a usage cap to the export endpoint." Once a branch exists, the stage should move from in_progress to in_review. The server exposes three tools.

get_ticket requires tickets:read. It returns id T-1042, stage in_progress, version 17, the assignee and the acceptance line, but not unrelated customer notes.

list_pull_requests requires repo:read. It returns the matching branch and an open pull request URL, and nothing from other repositories.

update_ticket_stage requires tickets:write. Its arguments are the ticket id, expected_version, from_stage, to_stage and a reason capped at 280 characters. The server accepts to_stage: in_review only when from_stage is in_progress and expected_version matches the current version.

The host lets the two reads through without a prompt. For the write, it asks for confirmation and shows the arguments: T-1042, version 17, in_progress to in_review, reason "PR opened against the usage-cap branch." The audit line should later name the person, the session, the tool, version 17 to 18, and the time.

Before you trust this setup, test three failures.

  • A teammate edited the title, so version 17 is now 18. The write is rejected, and the agent reads the ticket again instead of forcing version 18.
  • The token lacks tickets:write. The server rejects the call before it looks at the stage graph.
  • The model asks for to_stage: done. The schema or the stage graph rejects it, so the agent can't skip review by inventing an argument.

If the write can be retried, add a fourth. After a timeout, the host repeats the call with the same idempotency key. The server returns the original success, version 18, and does not create a second history entry.

The same shape works for a file or a feature flag: a narrow read, a versioned write, and confirmation when the change affects other people. Read the flag and its version, and apply a change only for a named staging environment. Refuse production unless the scope is admin and a person confirms. The model can't widen the environment list with a field the schema doesn't have.

A published MCP tool catalogue and an MCP server that plans from the git repository are one way to put this on a real board. Falrow rejects a stale ticket write instead of overwriting a newer stage. The protocol doesn't require that check. Your server should do it anyway.

What to review before you connect a server

Run through this once per server, and again whenever the tool list changes.

  • List every tool that writes, sends, deletes or invites a person. If the list is long, you don't have a permission model yet.
  • Map each write tool to a scope and a human role. If the only role is "the agent," add one.
  • Edit the record in the UI while the agent is mid-plan, and confirm the stale write gets rejected.
  • Check that missing scope, wrong version and illegal transition each return a useful error. A generic 500 makes the model retry.
  • Read one audit line out loud. If you can't tell what changed, the log is incomplete.

A ticket read, a repository read and a branch write can each be reasonable on their own and still combine to land in the wrong repo, so allow specific repository slugs in policy. AI coding agents stay useful when the tool surface is boring and explicit.

For each tool, write down the verb, the object, the scope, whether a person must confirm, and the failure you expect on a stale version. If a cell stays empty, the tool stays disconnected or read-only.

Run the stale-write test with a second client. Let the agent read version 17, edit the title in the UI so the version becomes 18, then let the agent send the write. You should get stale_version and no stage change. The title edit should still be there, and the next proposal should be built against version 18. Someone who wasn't in the review should be able to say what changed, who allowed it, and how they would undo it. Repeat the review when a description changes: a description that stops saying "does not write" is a behavior change even if the schema looks the same, so pin the description with the version you approved.

Where tool policy meets the rest of the work

Permissions can encode how a team works, but they can't stand in for agreeing on it. If the board has no rule about who may move work to done, the tool will make one up from the prompt. Write the rule first, then make the schema match it.

AI project management goes wrong when the agent can see every record and change any of them. It works better when reads are wide enough to plan and writes are narrow enough to review. Claude Code for teams and OpenAI Codex for software teams both do better work when the server they call already encodes stage gates, repository limits and version checks.

People decide the scopes, the stages and which repositories an agent may touch. The agent proposes plans inside those limits for a reviewer to accept. Falrow is one place to keep those limits, because the ticket rules the agent reads are the same rules the write tools enforce. Any careful server can do this if you treat the tool list as a production API. Start with read-only tools, then add the version-checked stage move above.

Watch the rejections before you widen access. A stream of illegal_transition means the model is asking for moves your board doesn't allow, so tighten the description or the enum. A stream of stale_version means people and agents are editing the same records, which is a reason to keep the version check. A stream of missing_scope means the grant doesn't match the job. Change the grant or the job, and don't add a fallback tool that writes with the read token.

Add writes one at a time. Give each a scope, a confirmation rule and a stale check, then run the same three failures. Leave unused vendor tools out of the catalogue the model sees, because a tool the model can name is one it will eventually call.

Common mistakes when shipping mcp tools

These tend to show up in mcp tools after a first demo has already gone well. Fix them in the server and the host before you tune prompts. Prompt text can name the tool you prefer. It won't stop a hidden write, and it won't put back a version the schema let the client skip.

A read tool that writes. A get_ticket that assigns the ticket to the agent or starts a response clock is a write, but people allow it on the read scope because the name says get. Split the mutation out, or require the write scope. Otherwise a planner that reads twice will assign twice.

A version the model is trusted to remember. Context gets summarized, and a later turn will drop the version or reuse one from a different ticket. Require expected_version and refuse the call when it is missing. Applying the write against "whatever is latest" is how you overwrite a newer edit.

One scope for the whole server. A token that means "this user may use the integration" pushes every tool decision into the prompt. Split read and write even if you split nothing else. If the token can't call a write tool, leave that tool out of the session catalogue so the model doesn't plan around a call that will only fail.

Logging the arguments in full. A reason and a title are often fine. A file body or a customer export will put secrets into the audit log and the transcript. Log identifiers, versions and hashes.

A confirmation the host accepts on a timeout, or accepts again after the arguments change. The yes covers that argument set only, and a changed ticket id cancels the approval.

FAQ

What are MCP tools?

MCP tools are functions an MCP server exposes to a client. Each one has a name, a description and an input schema. The model picks a tool and fills in the arguments, then the client and server decide whether the call is allowed and return the result. Tools sit alongside resources and prompts, which cover reading data and reusing prompt text.

How is MCP security different from prompt rules?

Prompt rules ask the model to behave. Host and server checks decide whether a call runs at all. Consent, a missing scope and rejected arguments still apply when a later message tells the model to ignore an earlier instruction. Use prompts to explain intent, and use host policy and server checks to enforce it. A polite system prompt can't replace either check.

What does MCP OAuth authorize?

MCP OAuth authorizes the client to a remote server. The token identifies the client and carries scopes, such as read or write on a resource. It doesn't prove that any particular argument is safe, so schema limits, version checks and an audit log still belong on top of a valid token. A valid token with a broad scope still grants a broad permission.

How do you make writes through MCP tools safe?

Read the record, keep the version the server returned, and send that version back with the write. Reject the call when the version is stale, the scope is missing, or the transition isn't one your workflow allows. For changes that are hard to undo, split propose and apply, and store an idempotency key so a retry doesn't apply twice. Log who called which tool against which version.

More on ai agents & mcp