{"slug": "how-to-build-a-read-only-mcp-server-when-an-api-lacks-a-read-only-oauth-scope", "title": "How to Build a Read-Only MCP Server When an API Lacks a Read-Only OAuth Scope", "summary": "A read-only Model Context Protocol (MCP) server can restrict which tools an AI client calls, but it cannot strip write permission from an upstream API token when the provider offers no read-only OAuth scope, according to guidance citing the MCP authorization documentation. The guidance recommends exposing a fixed set of named retrieval tools such as `get_record` or `list_records`, keeping the API credential server-side, validating incoming MCP client tokens on issuer, audience, expiration and permissions, and never passing the client's bearer token through to the upstream API. It also advises checking whether the provider supports a read-only account, narrower token or separate gateway before building a wrapper, since OAuth token exchange (RFC 8693) and rich authorization requests (RFC 9396) only narrow permissions when the authorization server and API enforce them.", "body_md": "### What Plan Mode Does in Claude Code and When It Is Worth Using\n\nWhen you ask Claude Code to change software, Plan Mode lets you review Claude’s proposed approach before it edits source files. It…\n\nA Model Context Protocol (MCP) server lets an AI client call named tools, which are functions that connect to external services. If the service’s API has no read-only OAuth scope, the access token available to the MCP server may authorize both retrieval and changes. A read-only MCP server limits the tools the client can call, but that limit alone does not remove write permission from the upstream token.\n\nExpose a fixed set of retrieval operations. Keep the API credential on the server, and reject every request outside that set. For stronger protection, make the API or an independent gateway reject writes too. An OAuth scope is a permission attached to a token; when the provider offers no read-only scope, the MCP server must not claim that its narrower interface has changed the token’s permissions.\n\nThere are two authorization boundaries. The MCP server decides which authenticated clients can call its tools. The upstream API decides what the server’s API token can do. Restricting one boundary does not automatically restrict the other.\n\nAuthenticate MCP clients using the MCP server’s own authorization setup. Validate the incoming token according to that setup. Check its issuer (who issued it), audience (the service it is meant for), expiration, and permissions. Then use a separate, server-side credential for the upstream API. Do not pass the MCP client’s bearer token through to the API: it was issued for a different purpose and may have different permissions. MCP authorization guidance describes the server’s role in validating tokens; it does not change the upstream API’s authorization rules. See the [MCP authorization guidance](https://ts.sdk.modelcontextprotocol.io/v2/serving/authorization).\n\nBefore building a wrapper, check whether the provider supports a read-only account, a more narrowly authorized token, or a separate gateway. OAuth token exchange and rich authorization requests let a client ask for narrower permissions, when the authorization server and API support and enforce those limits. Neither mechanism creates read-only authority when the provider does not recognize or enforce it. The [OAuth security best current practice](https://www.rfc-editor.org/rfc/rfc9700.html), [token exchange standard](https://www.rfc-editor.org/rfc/rfc8693.html), and [rich authorization requests standard](https://www.rfc-editor.org/rfc/rfc9396.html) all support minimizing permissions, but the provider’s implementation determines which restrictions actually apply.\n\nGive the MCP server a small, explicit set of named tools, such as `get_record` or `list_records`. Each tool should call a known API endpoint with a fixed method and a constrained set of inputs. For example, a tool for retrieving one record should accept a validated record identifier and pass it to the specific API route for that record.\n\nAvoid a general-purpose tool that accepts a URL, HTTP method, headers, and request body. That design lets callers choose operations beyond the server’s intended read interface. Also avoid arbitrary query-language tools unless the upstream API and the query layer independently restrict what the query can do.\n\nMake the server deny anything it has not explicitly approved. Each tool handler, the code that runs when a client calls a tool, should validate its inputs, build the API request itself, and return only the fields the client needs. Limit how many pages a caller can request, the size of each response, how long requests can take, and how often callers can send requests. Do not let caller-controlled input choose the upstream host or add arbitrary headers.\n\nUse HTTP methods as an initial check, then verify what each API endpoint actually does. HTTP classifies methods such as GET as “safe,” meaning they are intended to retrieve data without changing server state. But an endpoint can still cause side effects. For example, an endpoint might use a query parameter to request an action and trigger a change even when the request uses GET. The [HTTP semantics standard](https://www.rfc-editor.org/info/rfc9110) explains why a method allowlist alone cannot establish that an operation is read-only.\n\nCheck the API documentation and test the selected endpoints to confirm that they retrieve data without changing state or triggering workflows. Review exports, administrative routes, and endpoints that start background work with the same care. OWASP’s [Broken Function Level Authorization guidance](https://api-security.owasp.org/editions/2023/en/0xa5-broken-function-level-authorization) supports granting access to specific functions and denying unapproved ones. A fixed mapping from each approved API route to an MCP tool is easier to review than a rule that assumes a route is safe based on its name or HTTP method.\n\nKeep the upstream token out of tool results and error messages. Avoid logging the token or unnecessary sensitive response data. Retrieved records also remain untrusted input: their text can try to influence an AI client or its later tool calls. Read-only describes whether an operation changes upstream state; it does not mean the returned data is safe to follow or share.\n\nA fixed list of tools and carefully written handlers reduce the risk of accidental or ordinary misuse. They do not make a broad upstream token read-only if an attacker compromises the MCP server or its credentials. The server could then use the token outside the intended tool path.\n\nFor a stronger guarantee, ask the API provider for a read-only identity, or have a separate gateway enforce which routes and actions the server can use. The MCP server must not be able to bypass that gateway to reach the API directly. If neither the API nor an independent boundary enforces the restriction, describe the server accurately as exposing a read-only interface, while recognizing that its upstream credential remains write-capable.\n\nMCP tool annotations, metadata labels for tools, can describe how a tool is intended to behave. Set `readOnlyHint` only for a handler that has been constrained and tested. The [MCP discussion of tool annotations](https://blog.modelcontextprotocol.io/posts/2026-03-16-tool-annotations) treats annotations as hints for clients; handlers can still make write requests.\n\nTest every approved retrieval tool, then verify that the server rejects unapproved tools, routes, methods, and parameters. Include attempts to substitute a method, add action-like query parameters, select another host, provide malformed identifiers, or request excessive pagination. Test authentication failures too, including missing, expired, wrong-issuer, and wrong-audience MCP tokens.\n\nUse a test environment for endpoint behavior checks when one is available. When the API changes, review the tool-to-endpoint mapping and repeat the relevant tests. These checks provide evidence that the server follows its intended boundary; they do not prove that a broad upstream credential remains harmless after a server compromise.\n\nGive Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.\n\nTake a look at vroni.com", "url": "https://wpnews.pro/news/how-to-build-a-read-only-mcp-server-when-an-api-lacks-a-read-only-oauth-scope", "canonical_source": "https://www.vincentschmalbach.com/how-to-build-a-read-only-mcp-server-for-an-api-that-has-no-read-only-oauth-scope/", "published_at": "2026-11-18 09:25:04+00:00", "updated_at": "2026-11-18 09:41:50.751576+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "ai-safety"], "entities": ["Model Context Protocol", "Claude Code", "OAuth", "RFC 9700", "RFC 8693", "RFC 9396"], "also_reported_by": [], "takeaway": "When an upstream API has no read-only OAuth scope, expose only fixed named tools like `get_record` with validated inputs, keep the API credential server-side, and never forward the MCP client's bearer token, because the server's tool limits do not change the token's upstream permissions.", "recommendation": {"advice": "Scope MCP servers to fixed named retrieval tools with validated inputs and a server-side API credential, and never pass the client's bearer token upstream, since tool limits alone don't remove the token's write permission.", "playbook": "agent-security", "playbook_url": "https://wpnews.pro/playbooks/agent-security"}, "alternates": {"html": "https://wpnews.pro/news/how-to-build-a-read-only-mcp-server-when-an-api-lacks-a-read-only-oauth-scope", "markdown": "https://wpnews.pro/news/how-to-build-a-read-only-mcp-server-when-an-api-lacks-a-read-only-oauth-scope.md", "text": "https://wpnews.pro/news/how-to-build-a-read-only-mcp-server-when-an-api-lacks-a-read-only-oauth-scope.txt", "jsonld": "https://wpnews.pro/news/how-to-build-a-read-only-mcp-server-when-an-api-lacks-a-read-only-oauth-scope.jsonld"}}