Local HTTP mode

This page explains local HTTP mode: the HTTP (HyperText Transfer Protocol) server that email-mcp serve --http starts for an AI (artificial intelligence) app that cannot start a program. It covers the checks that a request passes before it reaches a tool, the access tokens, the stateless server, and the choice that lets a token answer a confirmation in its own window. Read it before you change the package httpserve, the HTTP part of serve, or the tokens. After the checks, a tool call takes the same steps as on stdio (standard input and output: the AI app starts the program and talks to it through two pipes). See One tool call, step by step. The manual page Local HTTP mode has the steps for the person.

Where it listens

checkServeFlags in cmd/email-mcp/serve.go checks the flags before anything is opened, and a bad one ends the command with the exit code 2. httpserve.CheckLoopbackAddr refuses the address of --http unless it is a loopback address (an address on this computer that no other computer can reach) with a port: an IPv4 (Internet Protocol version 4) address in 127.0.0.0/8, [::1] or localhost. The address must be written exactly: brackets only around an IPv6 (version 6) address, and an IP address in its usual short form. So 0.0.0.0:8765 and [127.0.0.1]:8765 are refused. Only 127.0.0.1, [::1] and localhost pass the Host check, so use one of these. Any program on this computer can reach the address, so the token decides who may use the server.

--allow-origin adds a browser origin (the scheme, host and port of a web page, such as http://localhost:5173) that may call the server. It needs --http. Add only an origin that you trust. httpserve.NormalizeOrigin refuses null, and an origin with a path, a query or a fragment. The MCP (Model Context Protocol) endpoint is /mcp (mcpPath). When the server listens, it logs “serving MCP over local HTTP” with the address and the path.

The checks, in order

The checks of a request to serve --http The steps of a request to serve --http, from top to bottom. A request that limitRequests or httpserve refuses gets a fixed text and a fixed log code. 1, limitRequests in serve.go lets at most 8 requests run at once (maxConcurrentRequests). A request over the limit waits up to 30 seconds (requestQueueWait) before its body is read, and then gets 503 Service Unavailable with Retry-After: 1, log code too_many_requests. 2, the router of serveHTTP (http.ServeMux) passes on only the path /mcp. Any other path gets 404 Not Found, and a path that is not clean, such as //mcp, gets a redirect to its clean form (307 Temporary Redirect with Go 1.27.3, the Go version of the release build). The router logs nothing. 3, the Host check of httpserve: the connection came in on a loopback address, and the Host header is exactly localhost, 127.0.0.1 or [::1] with the port of the connection. Else 403 Forbidden, log code bad_host. 4, the Origin check: no Origin header, or exactly one whose value is in the allow-list of --allow-origin. Else 403 Forbidden, log code bad_origin. 5, the stated body size: a Content-Length over 15 MiB (MaxBodyBytes) gets 413 Request Entity Too Large, log code body_too_large. 6, the bearer token, checked by tokens.Manager.Verify: a bad token gets 401 Unauthorized with the text invalid token, log code invalid_token, and a check that fails for another reason gets 500 with the text internal error, log code token_check_failed. 7, readBody reads the whole body: over 15 MiB it gets 413, log code body_too_large, and a body that cannot be read gets 400 Bad Request, log code body_unreadable. 8, the MCP handler of the SDK, in stateless mode: the server keeps no session between two requests. 9, the middleware: trackToolCalls, capture and the multi round-trip middleware of the SDK. 10, the tool: safe, the tool handler, then service. Steps 9 and 10 are the same as on stdio. 1 limitRequests at most 8 at once; a wait of up to 30 seconds 503 Service Unavailable too_many_requests 2 Path the router passes on only /mcp 404 or a redirect not logged 3 Host loopback connection, exact Host header 403 Forbidden bad_host 4 Origin none, or one in the --allow-origin list 403 Forbidden bad_origin 5 Stated body size Content-Length at most 15 MiB 413 Request Entity Too Large body_too_large 6 Bearer token verifier: tokens.Manager.Verify 401 Unauthorized or 500 when the check fails 7 Read the body readBody: at most 15 MiB 413 or 400 body_too_large, body_unreadable 8 SDK handler, stateless no session between two requests 9 Middleware trackToolCalls, capture, multi round-trip 10 The tool safe, the tool handler, then service Steps 9 and 10 are the same as on stdio.

serveHTTP builds the handler from three layers. limitRequests in serve.go is the outer one. In the middle, a router (http.ServeMux, the path router of the Go standard library) passes on only the path /mcp. httpserve.Handler in internal/httpserve/httpserve.go is the inner one. The SDK (software development kit) is the official Go library for MCP, go-sdk. A bearer token is a secret in the header Authorization: Bearer <token>. A MiB (mebibyte) is 1,048,576 bytes. A request goes through these steps, in this order:

Step Code Refused with Log code
1. Concurrency limit limitRequests: at most 8 requests at once (maxConcurrentRequests). A request over the limit waits up to 30 seconds (requestQueueWait) for a free place, before its body is read. 503 (Service Unavailable), with Retry-After: 1 too_many_requests
2. Path The router passes on a request whose path is /mcp (mcpPath), with any method. It answers any other path itself. A path that is not clean, such as //mcp, gets a redirect to its clean form. 404 (Not Found), or a redirect to the clean path (307, Temporary Redirect, with the newest stable Go, which the CI (continuous integration) builds and the release build use; older Go versions send 301) none
3. Host hostAllowed: the connection came in on a loopback address, and the Host header is exactly localhost:<port>, 127.0.0.1:<port> or [::1]:<port>, with the port of the connection (LoopbackPort). 403 (Forbidden) bad_host
4. Origin originAllowed: no Origin header, or exactly one whose value is in the list of --allow-origin. 403 bad_origin
5. Stated body size A Content-Length over 15 MiB (MaxBodyBytes) is refused at once. Any other body is cut at that limit while it is read (http.MaxBytesReader). 413 (Request Entity Too Large) body_too_large
6. Bearer token auth.RequireBearerToken of the SDK, with verifier, which calls tokens.Manager.Verify. 401 (Unauthorized), or 500 (Internal Server Error) when the check itself fails invalid_token, token_check_failed
7. Read the body readBody reads the whole body before the MCP handler runs. 413 over the limit, 400 (Bad Request) when it cannot be read body_too_large, body_unreadable
8. MCP handler mcp.NewStreamableHTTPHandler in stateless mode, with MaxRequestBodyBytes set to MaxBodyBytes. The SDK answers. none

After step 8, the request is a tool call as on stdio: the middleware (functions that wrap the handling of every request: trackToolCalls, capture and the multi round-trip middleware of the SDK, which lets a tool answer “I need input”; see Stateless mode), safe, the tool handler and service.

Why this order:

  • The Host check comes before the token. It stops a web page that uses DNS rebinding (DNS is the Domain Name System; in DNS rebinding, a name of the attacker points to 127.0.0.1). Such a page gets 403 on /mcp, or the 404 or the redirect of the router on another path, before any token is looked at. TestHTTPCheckOrder in internal/httpserve/httpserve_test.go checks the order of Host, Origin, the body size and the token.
  • A request with an Origin header comes from a browser, and the list of --allow-origin is empty by default. Programs send no Origin. The handler sends no CORS headers (CORS, cross-origin resource sharing, is the set of headers that lets a page read the answers of another origin).
  • limitRequests waits before the body is read, so a waiting request holds no body. readBody runs after the token check, so it does not run for a caller without a token.

Each refusal of limitRequests and httpserve has a fixed text, which never repeats a value of the request. Most texts are the standard text of the status, such as “Forbidden”. The SDK writes the text of the token check: “invalid token” for a bad token, and “internal error” for a check that failed for another reason (errTokenCheck). A request without the Authorization header, or with one of another form, gets the SDK’s 401 with “no bearer token”, and is not logged. The log gets the fixed code of the table, and never a token, the Authorization header or a body. The 404 and the redirect come from Go’s router, and they are not logged.

Tokens

An access token is the secret that the AI app sends with each request. Its rules are in internal/tokens/tokens.go:

  • A token is emcp_ (prefix) and 52 characters: 32 random bytes (randomBytes) in lower-case base32 (the letters a to z and the digits 2 to 7), without padding. The prefix makes a token easy to find, for example for a tool that looks for secrets in code.
  • The store keeps only the SHA-256 of the token (SHA is Secure Hash Algorithm; the hash is a short value from which the token cannot be read back). The plain token exists only in the answer of Create, so the person copies it then. The page Storage and secrets has the table api_tokens.
  • A token has an explicit list of known scopes. A scope is a permission that a token carries, such as email:read. Create refuses a token with no scope, or with one that policy does not know, and stores the list sorted, with each scope once. What the scopes allow is on Permissions.
  • A token has an end date. Create takes a lifetime from 1 minute (MinLifetime) to 3,650 days (MaxLifetime), and 90 days (DefaultLifetime) when it gets none. A stored token with no end date works until it is revoked, so the person should make a token to replace it and revoke the old one.
  • A token may answer a confirmation in its own window only when the person chose that when the token was made (InBandConfirm). See Who gets which channel.
  • A name is 1 to 128 bytes (maxNameBytes) of UTF-8 (Unicode Transformation Format, 8-bit) text (the usual way to write text as bytes), without a control character, a format character, or a line or paragraph separator, which could change how a terminal shows the list. The manual and the error of token create say “128 characters”. That is the same for ASCII (American Standard Code for Information Interchange: the basic Latin letters, digits and signs). A character outside ASCII takes 2 to 4 bytes, so a name of such characters holds fewer than 128 of them.

Manager.Verify checks a token. It refuses a token of the wrong form before any lookup (wellFormed). Each token has one spelling, so upper case, padding and line breaks are refused. Then it looks up the SHA-256, and compares the stored hash again in constant time (a comparison whose time does not depend on the bytes). It refuses a revoked token, an expired token and a token with no scope. Every refusal is the same error, ErrInvalidToken, so the answer does not say why. TestHTTPBadTokensGetTheSameAnswer checks that a malformed, an unknown and a revoked token get the same answer. A valid token notes its last use at most once a minute (useGap). The manager keeps no cache, so a revoke counts at the next check.

verifier in httpserve turns the result into the TokenInfo of the SDK: the tenant (the owner of a set of accounts) as UserID, the scopes, and the id and the in-band choice of the token in Extra. These values come from the token check, not from the request. httpserve.Principal then makes the principal (the caller of a request) for the tool call, of the type service.Principal in internal/service/principal.go:

  • A call without a TokenInfo or without a UserID is refused with ErrNoToken.
  • The scopes are a copy of the list and are never nil, so a token never means “no limit”. A nil list (no limit) belongs to the callers without a token: stdio, the web portal and the commands.
  • A missing or odd value in Extra means no token id and no in-band confirmation.
  • The client name comes from the request. It is not trusted, and the activity log cleans it.

The person makes a token with token create in cmd/email-mcp/token.go, or on the Connections page of the web portal: internal/web/connections.go and internal/web/templates/connections.html. Both call Service.CreateToken in internal/service/tokens.go, which writes the activity log entry token_created, or token_created_in_band for a token that may answer in its own window. Service.RevokeToken writes token_revoked. No tool reaches these use cases. token list and the Connections page show the tokens with Manager.List, which never returns a token or its hash. Only the command sets a lifetime (--expires-in). The page uses the default.

Stateless mode

httpserve.Handler makes the MCP handler with Stateless: true. The server keeps no session (no state that lasts from one request to the next): each request carries its token, and the token decides the caller. serveHTTP builds one MCP server for all requests, because the SDK asks for the server more than once in one request.

What this changes:

  • The server cannot send a request to the client. So it does not send elicitation/create (the request that asks the client to show a form) over HTTP. serveHTTP sets InBandLegacyElicitation to false.
  • A client that speaks the protocol version 2026-07-28 or newer can still get the question, inside the result, when its token was made with the choice to answer in its own window. This is MRTR (multi round-trip request): the tool answers “I need input”, and the client calls again with the answer. See Who gets which channel for every condition.
  • Every other client gets the approval link for each confirmation: a client of an older protocol version, a client without form elicitation, and a client whose token was made without that choice. The approval link leads to the page of the web portal where the person approves or rejects the action.

The design of the program chose this over a server that keeps sessions for older clients, and accepted that those clients get the approval link.

Who gets which channel

canElicitInBand in internal/mcpserver/elicit.go decides whether the client can show the confirmation form in this call (in band). It needs a caller that may confirm in band (Principal.InBandConfirm), form elicitation in the capabilities of the client (what the client says it can do), and a way to ask (canAsk): the protocol version 2026-07-28 (mrtrProtocolVersion) or newer, or InBandLegacyElicitation. Form elicitation is a way for a server to ask the person a question through a form in the AI app. A protocol version is a date that names a version of the MCP rules.

Caller Client with form elicitation, protocol 2026-07-28 or newer Client with form elicitation, older protocol Client without form elicitation
stdio (localPrincipal: InBandConfirm is true) In band, as an input request in the result In band, with elicitation/create in the same session Approval link
HTTP, with a token made with --in-band-confirm or the box “Let this app ask me in its own window” In band, as an input request in the result Approval link Approval link
HTTP, with any other token Approval link Approval link Approval link

The answer of an in-band form is only as good as the client: the client decides whether a person saw the form. A client that holds a token with this choice can answer the form by itself. So for a token, InBandConfirm is false by default, and the choice is the person’s, made when the token is made. Make a token with this choice only for an app that shows you the form. On stdio, the AI app that started the process holds the other end of the pipes, so the answer comes from that app. A program that runs as the same user is outside what email-mcp can control. The page The send flow shows the two calls of an in-band question.

The table is for confirmations. canOpenLink uses the same rule for the protocol to let the client open the link of connect_account or request_permission_change for the person. That link holds no secret.

Limits and timeouts

Name Value What it bounds
maxConcurrentRequests (serve.go) 8 Requests that run at once. A request can hold its body twice: httpserve reads it, and the SDK reads it again.
requestQueueWait (serve.go) 30 seconds The wait of a request over the limit, before 503
MaxBodyBytes (httpserve.go) 15 MiB The body of a request. A message may have 10 MiB of attachments (mime.MaxAttachmentBytes), and base64 (the text form of bytes in a mail) makes them a third larger.
httpMaxHeaderBytes (serve.go) 64 KiB The headers of a request. A KiB is 1,024 bytes.
httpReadHeaderTimeout (serve.go) 10 seconds Reading the headers
httpReadTimeout (serve.go) 1 minute Reading the whole request
httpIdleTimeout (serve.go) 2 minutes An open connection that waits for its next request
httpPrepareMargin (serve.go) 5 minutes The checks of a tool call before its send, and the calls to the mail server of a reply or a forward
httpWriteTimeout (serve.go) 19 minutes 30 seconds Writing the answer, counted from the end of the request headers
DefaultLifetime, MinLifetime, MaxLifetime (tokens.go) 90 days, 1 minute, 3,650 days The lifetime of a token
useGap (tokens.go) 1 minute The shortest time between two writes of the last use of a token
maxNameBytes (tokens.go) 128 bytes The name of a token

httpWriteTimeout is `requestQueueWait + httpReadTimeout + outbox.SendDeadline

  • httpPrepareMargin: 30 seconds, 1 minute, 13 minutes and 5 minutes. Before the answer, a request may wait for a place, read its body, prepare the message, and send it with no undo window (the time when a send can still be cancelled) for up to outbox.SendDeadline`. A client that never gets the answer of a send that went out could send it again. So the answer must still go out.

How the server stops

When serve gets Ctrl-C (hold the Ctrl key and press C) or SIGTERM (the signal that asks a program to stop), serveHTTP calls App.BeginStop, stops taking connections, and waits for the requests that run. The wait is within the stop budget (stopBudget: one time limit for the whole stop, app.StopTimeout). Then serve calls App.Close with the same budget. The page Startup and shutdown gives each step and what happens to a request that does not end in time.

Code covered by this page