00Case study · Dec 2025 – Sep 2026

MCP server and OAuth for outside AI clients

The product’s data and actions as 72 typed tools, usable by its own agent and by Claude, ChatGPT, Cursor and VS Code.

StaffShipped

My roleCreator and primary author of the MCP server and the OAuth discovery service, and author of the MCP authorizer changes.

72 tools
2 transports
2 AWS regions
4 client families

01Overview

What it is, and why

I built the product’s Model Context Protocol server, the standard plug-in interface that lets AI agents call outside tools. It exposes the product’s data and actions as 72 typed tools: the product’s own assistant uses it, and so can customers’ AI apps such as Claude, ChatGPT, Cursor and VS Code.

Serving two callers sets the constraints. Outside clients need a public endpoint and standard OAuth sign-in in more than one region, and every tool call has to carry the user’s real permissions, not a shared service account.

The tools are called by models, so they also have to be easy for a model to choose and to call in the right order.

At a glance

How it works, in short

Permissions on every call: each tool runs with the signed-in user’s real role and application access; write tools are labelled destructive and risky tools are off.
Standard OAuth sign-in for outside clients: a small service publishes the protected-resource metadata document (RFC 9728) and a token checker in each region validates tokens.
Public endpoint protection: a web application firewall with a per-user rate limit and a block list, plus a per-company on/off switch.
Usability for models: tool annotations (read-only, destructive, open-world), templated workflow guides and on-demand tool discovery, so the model sees only relevant tools.

Python
MCP
OAuth 2 / RFC 9728
JWT
AWS WAF
CDK

02Timeline

How it came together

Dec 2025 to Sep 2026.

Dec 2025
Prototype inside the backend, then its own service.
Feb 2026
Typed schemas and the integration-metadata tools.
Mar 2026
Workflow guides consolidated.
Jul 2026
OAuth discovery, the dedicated authorizer, per-region deploys, provisioned concurrency.
Aug 2026
Tool annotations, the firewall, role and application scoping.
Sep 2026
The same tools as a plain REST endpoint.

03Architecture

How the parts fit

Outside clients discover sign-in, pass the firewall and a per-region token check; the product’s assistant uses an internal API. Both reach the same typed tools.

mcp · two callers, one registry

Callers
- Outside AI clientsClaude, ChatGPT, Cursor, VS Code
- Other systemsPlain REST, no MCP needed
- In-product assistantThe signed-in user’s session
Edge · per region
- OAuth metadataRFC 9728 document, no function to run
- FirewallPer-user rate limit, IP block list
- Token checkerRegion’s issuer and audiences
- Internal APISession-authenticated
MCP server · AWS Lambda
- TransportsStreamable HTTP and SSE
- Tool registry72 typed tools, scoped to the caller
Product
- Backend servicesInvoked per tool call

Outside AI clients to OAuth metadataDiscover the authorization server and the token audience
Outside AI clients to FirewallTool calls with a bearer token
Other systems to FirewallThe same tools as a plain REST call
Firewall to Token checkerRate-limited per user; known bad IPs blocked
Token checker to TransportsA valid token, with the user’s role and application access
In-product assistant to Internal APITool calls from the product’s own agent
Internal API to TransportsSame tools, same permission checks
Transports to Tool registryTyped input, validated against the tool’s schema
Tool registry to Backend servicesThe product’s backend functions do the work

Point at a box or a flow to trace it. The numbers match the list.

04Inside the system

The parts that matter

01
Tools a model can use well
- A schema-generating registry: Pydantic inputs, typed outputs and versioning.
- Annotations on every tool (read-only, destructive, open-world); policy create and update tools are marked destructive, and risky tools are off.
- Templated workflow guides, served as tools, teach the order of a query: read which filters exist, then filter by value.
- Covers alerts, assets, applications, identities, tags, policies and SLAs, automations, fixes, tasks and integration metadata.
02
Permissions on every call
- Each call runs with the role and application access the authorizer passes on, read from the user’s real permissions, not hardcoded.
- A per-company switch turns the public endpoint on or off.
03
Sign-in clients find on their own
- The protected-resource metadata document (RFC 9728) at the standard well-known path, from an API Gateway mock integration with per-region values set at deploy time.
- A dedicated OAuth-only authorizer in each region.
- New customer organizations are created ready for AI-client login from day one.
04
Running a public endpoint
- A dedicated firewall with a per-user rate limit and an AWS-managed list of known bad IPs, answering 429 when a client goes over.
- Provisioned concurrency, so a client’s first connect does not wait on a cold start; ARM64 functions.
- Region-matrix deploy workflows.

05Deep dive

Hard problems

What stood in the way, what I did, and what came of it. Where nothing was measured, it says so.

Hard problem 01

Sign-in for any compliant client, in every region

Problem: Outside clients find their sign-in through OAuth discovery. The product runs in more than one region, each with its own issuer, and permissions are scoped by role and by application.
What I did: A tiny metadata service publishes the protected-resource document per region.
A dedicated OAuth-only authorizer validates each token against its region’s issuer and audiences, and forwards role and application scope to the tool registry.
A first authorizer attempt was replaced by this cleaner split.
New customer organizations are set up MCP-ready when they are created.
Result: Sign-in merged in Jul 2026, role and application scoping in Aug: outside AI clients get single sign-on, and each user’s permissions apply on every tool.

Hard problem 02

Teaching a model a two-step query

Problem: Filtering product data takes two steps: read which filters a data type supports, then filter by value. Every client’s model has to know that order.
What I did: Workflow guides served as tools, templated per ticketing vendor and for generic filtering.
The filter guides consolidated into one set the model can discover.
Result: The order lives in the server, not in every client’s prompt.

06Decisions

Trade-offs I made

What I chose, what I passed on, and why.

Decision · Discovery
An API Gateway mock integration with deploy-time values
OverA function that serves the JSON
Nothing to run, scale or patch; each region’s values come from parameters at deploy time.
Decision · Callers
Two APIs (session and OAuth) over one tool registry
OverA separate server per caller
One set of tools and one set of permission checks for the product’s agent and for outside clients.
Decision · Transport
Stateless Streamable HTTP on Lambda, with SSE kept
OverA long-lived server process
Stateless requests fit Lambda; the SSE transport keeps older clients working.

07Outcomes

What came of it

Measured or owner-stated

Results

72 typed tools.
2 transports: Streamable HTTP and SSE.
2 AWS regions.
Supported clients: Claude, ChatGPT, Cursor and VS Code, plus the product’s own assistant.

Said plainly

Limits

No request-volume or latency figures are quoted.