One tool call, step by step
This page follows one call of the tool get_message from the MCP (Model
Context Protocol) client to the mail server and back. It shows where the
permission is checked, where the call is recorded, where the text of the mail
is cleaned, and where errors turn into the texts that the agent sees. Read it
before you change a tool or a use case: a job of the program for a caller, such
as reading one message.
MCP is the open standard that lets an AI (artificial intelligence) app call
the tools of another program. The MCP client is that
app, and the agent is the AI program inside it. IMAP (Internet Message Access
Protocol) is the protocol for reading mail. get_message reads one message:
its headers, a page of its body and the list of its attachments.
The steps
The numbers match the drawing. Step 1 has a part that runs only on HTTP (HyperText Transfer Protocol).
-
Transport. On stdio (standard input and output: the client starts the server and talks to it through two pipes),
serveStdioincmd/email-mcp/serve.goruns the server on anmcp.IOTransport. On HTTP only, two checks come first.limitRequestslets at most 8 requests run at once (maxConcurrentRequests), and a request over the limit waits up to 30 seconds (requestQueueWait) and then gets the status 503 (Service Unavailable). Thenhttpserve.Handlerchecks theHostheader, theOriginheader, the size of the body and the bearer token (a secret in theAuthorizationheader), in this order. The body is at most 15 MiB (httpserve.MaxBodyBytes; a MiB is 1,048,576 bytes). The page Local HTTP mode explains these checks. -
Middleware of the SDK. The SDK (software development kit) is the official Go library for MCP,
go-sdk. A middleware is a function that wraps the handling of every request, so it runs before and after it. From the outside in:App.trackToolCallsininternal/app/app.gocounts the tool call, so that a stop can wait for it. While the program stops, it refuses the call.captureininternal/mcpserver/capture.goputs a call trace in the context: a small record wheresafewrites the caller and the result.capturerecords the call when it ends (step 10).- The multi round-trip middleware of the SDK. Multi round-trip means that a
tool can answer “I need input”, and the client calls again with the
answer.
mcp.NewServeradds this middleware. - Then the SDK finds the tool by its name, and checks the arguments against the JSON (JavaScript Object Notation) schema of the tool: the description of the arguments that the tool accepts.
Each call of
AddReceivingMiddlewarewraps the handler that is there, so the middleware that was added last runs first.mcpserver.Newaddscapture, andApp.MCPServeraddstrackToolCallsafter it. The SDK adds its own middleware inmcp.NewServer, before both, so it runs inside both. A call to an unknown tool, or with arguments that do not match the schema, stops here.safeand the tool handler do not run for it.capture, which is also code ofmcpserver, has already run, and it still records the call. -
safe. The functionsafeininternal/mcpserver/server.gowraps every tool handler. It asksOptions.Principalfor the principal: the caller of the request, with its tenant (the owner of a set of accounts), the scopes of its access token (the permissions that the token carries; an access token is the secret that a program sends on local HTTP), and the name of the client. Without a principal or a tenant, the answer is “not authorized”, and the handler does not run. Thensafeputs the principal in the context (service.WithPrincipal), runs the handler, turns a panic into “internal error”, and turns an error into a tool result. OnlyaddToolregisters a tool, and it wraps the handler withsafe. So no tool can skip it. The testTestEveryToolRunsThroughSafecalls every tool that the server lists, and fails for a tool that was added another way. -
The handler.
getMessageininternal/mcpserver/read_tools.gochecks the arguments that the schema cannot check, such as a negativeoffset. Then it callsservice.GetMessagewith the account id, the ref and the options. A ref is an opaque string that names a message. The agent passes it back unchanged. -
The permission.
service.GetMessageininternal/service/read.gocallsmailBackend, which callsauthorizeininternal/service/service.go.authorizedoes these checks, in this order:- It reads the principal from the context (
service.PrincipalFrom). With none, the error isErrNoPrincipal. - It asks the store for the account in the tenant of the principal. When
the tenant has no such account, the error is
ErrAccountNotFound. - It calls
policy.Decidewith the account, the actionpolicy.ActReadand the scopes. A refusal is a*PermissionError, with a reason, and a link to the settings page of the account when there is one. There is no link when the scopes of the token lowered the level, or when the link cannot be built. - When the account must be reconnected, the error is a
*ReauthError.
The order is on purpose. A caller that may not read gets the permission error first, so it learns nothing about the connection of the account.
- It reads the principal from the context (
-
The backend cache. The backend of an account is the object that talks to its mail servers.
mailBackendgets the backend of the account fromBackendCache.Mailininternal/service/backends.go. The cache keeps one backend for each account. It builds a new one withimapsmtp.Newonly when the server settings or the stored password changed. The mail backend explains the slot, the fingerprint and when an old backend closes. -
The IMAP backend.
Backend.GetMessageininternal/provider/imapsmtp/fetch.gotakes a logged-in connection from the pool of the account: the small set of open connections that its calls share (internal/provider/imapsmtp/pool.go). It opens the folder read-only with the IMAP commandEXAMINE. It fetches withBODY.PEEK, the IMAP way to read a message without marking it as read. The packagemimedecodes the body. It turns HTML (HyperText Markup Language, the language of web pages) into text without the parts that a reader cannot see (mime.ReadableText). One page of the body has 20,000 characters by default (defaultBodyChars) and 100,000 at most (maxBodyChars). The page The mail backend explains the pool. -
Back in
service.noteBackendErrorlooks at the error of the backend. When it matchesimapsmtp.ErrAuthFailed(the server refused the stored login), it marks the account as one that must be reconnected. The next call then stops inauthorize, before it reaches the server. -
Back in
mcpserver.messageOutininternal/mcpserver/shape.goshapes the result. See “Where text from the mail is cleaned” below. -
The call entry. When the call ends,
capturewrites one call entry in the activity log: the log of the tool calls of the agent and of the actions of the use cases, also those that the person did on a page. The person reads it in the web portal (the local web site of the person). See “Where the call is recorded” below.
Where the permission is checked
In service, never in mcpserver. A tool handler checks no permission
itself.
- The use cases that a tool calls to read or change the mail of one account
call
authorize(step 5) before they read the account or its mail. Some, such asSend, first check that the program is not stopping (beginAction). The reads call it throughmailBackend. The writes,Send,TrashandCancelSendamong them, call it throughauthorizeWriteinwrite.go, whichbegincalls.SendStatuscalls it itself. Soauthorizeruns before any of these use cases calls a mail backend. ListAccountshas no account id. It lists the accounts of the tenant of the caller. It asks the backend of an account for its capabilities (what the backend supports, such as tags, and the most refs in one batch call) only whenpolicy.Decideallows reading and the account needs no reconnect (worthAskinginread.go).PermissionLinkandConnectLinkchange nothing and return a link.PermissionLinkchecks that the account is in the tenant of the caller.- No tool calls the use cases of the person (see
Architecture overview). They work only in the tenant of the caller.
Some, such as
UpdateSettings,RemoveAccountandProbeAccountinaccounts.go, check no level. Others also callauthorizefor the account of the action:ApprovePendingthroughbeginandauthorizeWrite, andPendingDetailfor a send that waits (sendDetailinapprovals.go).
So a tool that you add gets the check from its use case. That use case must
call authorize, or, for a write, authorizeWrite (alone or through
begin). The page Permissions in the
group “Inside the server” explains policy.Decide.
Where text from the mail is cleaned
The text of a mail comes from a third party, so it can hold hidden
instructions for the agent. messageOut cleans every string that a sender
controls with mime.CleanUntrusted. It removes characters that a reader cannot
see, and control characters. Then it puts the text that a sender wrote (the
name, the subject, the body and the names of the attachments) inside an
Untrusted wrapper, with the field "trust": "untrusted". An address stays
outside the wrapper only when it has the plain form that mime.IsPlainAddress
accepts.
The backend cleans text too, while it decodes the message: a text part goes
through cleanText, and the name of an attachment through partFilename, in
internal/provider/imapsmtp/fetch.go. Both use
mime.CleanUntrusted.
The result has two forms. The structured content is the JSON object. The text
copy is for clients that do not read structured content. textCopy makes it,
and its first line is always the fixed warning untrustedBanner. When the HTML
of the message may hide text, a second fixed line says so
(hiddenContentNotice). The page Mail content
explains the cleaning.
Errors become fixed texts
An error that a use case returns goes back up to safe. There toolError in
internal/mcpserver/errors.go matches it with errors.Is and
errors.As, never by its text, and picks a fixed text for the agent. The text
of the error itself does not reach the agent, because it can hold text from
the mail server or the name of an account. There is one exception: for a
*policy.RateLimitError, rateLimitFailure sends the text of the error. That
text is a fixed sentence that policy builds from the kind of limit and the
wait, and it names no account. The other parts that come from an error are
fields that the service filled for the agent: the reason and the link of a
*service.PermissionError, and the link of a *service.ReauthError.
An error with no known text becomes “internal error”. The program log (the log
that the program writes to standard error) then gets the name of the tool, a
fixed code and the Go types of the error (errtype.Chain), never its text. The
SDK turns the failure into a tool result with isError set.
Where the call is recorded
capture records every tools/call request that reaches it, also a call that
the SDK refused before a handler ran. It calls service.RecordToolCall in
internal/service/calls.go, which writes a call entry with the
audit package. A call that trackToolCalls refuses while the program stops
never reaches capture, so it has no entry.
The arguments are sealed with the key of the tenant. The arguments body,
html_body and data_base64 are never kept (omittedArguments). The page
Activity log and program log in
the group “Inside the server” explains the log and the rules for writing to
it.
What differs between stdio and HTTP
| Part | stdio | HTTP |
|---|---|---|
| Transport | mcp.IOTransport in serveStdio |
limitRequests, the checks of httpserve.Handler, then the SDK handler in stateless mode (the server keeps nothing between two requests) |
| Principal | localPrincipal: the tenant local, no scope limit |
httpserve.Principal: the tenant and the scopes of the token. The scopes are a list that is never nil, so a token never means “no limit”. |
| A question in the chat | The client may show the confirmation form, where the person answers yes or no (InBandConfirm is true) |
Only with a token that may confirm in band: one made with --in-band-confirm, or with the box “Let this app ask me in its own window” in the web portal. Other callers get a link to the approval page: the page of the web portal where the person approves or rejects an action. |
Steps 2 to 10 are the same code for both. serve builds one server for each
transport with App.MCPServer, with a different mcpserver.Options.
What changes for a write tool
A write tool, such as send_message, follows the same steps, with three
additions:
- The use case decides whether the person must confirm the action.
policy.Decidegives the setting of the account, and a send has more reasons. Thenconfirmstores the exact request, and the tool asks the question in the chat of the client, or returnspending_approvalwith a link to the approval page of the web portal. - The use case writes its own action entries in the activity log. So a call that changes something has a call entry and one or more action entries.
- A send goes to the
outbox, the queue of sends, which waits for the undo window (the time when the send can still be cancelled) and then delivers it. A send with no undo window runs inside its tool call, and that is whytrackToolCallscounts the call.
The page The send flow in the group “Inside the server” explains this path.
Related pages
- Architecture overview
- Map of packages
- What the agent can do in the user manual
- Confirmations in the user manual
Code covered by this page
cmd/email-mcp/serve.gointernal/httpserve/httpserve.gointernal/app/app.gointernal/mcpserver/server.gointernal/mcpserver/capture.gointernal/mcpserver/read_tools.gointernal/mcpserver/shape.gointernal/mcpserver/errors.gointernal/service/service.gointernal/service/read.gointernal/service/principal.gointernal/service/backends.gointernal/service/calls.gointernal/service/write.gointernal/service/accounts.gointernal/service/send.gointernal/service/approvals.gointernal/policy/limiter.gointernal/provider/imapsmtp/backend.gointernal/provider/imapsmtp/fetch.gointernal/provider/imapsmtp/pool.go