Connect a field service CRM to Claude and ChatGPT with MCP (OAuth, PKCE and the bugs we hit)
This post was written with AI assistance and checked against our production code. We just shipped a remote MCP server for Smarfle, field service software for home service businesses. The owner of a pest control or clean
This post was written with AI assistance and checked against our production code.
We just shipped a remote MCP server for Smarfle, field service software for home service businesses. The owner of a pest control or cleaning company can now ask Claude or ChatGPT "what's on today's schedule?" or "which invoices are unpaid?" and get the answer from their own account. They can also add a customer, a note or a job request.
This is what it took, including three bugs that only showed up with real clients.
The shape of the server
The server is one Next.js route handler at /api/mcp: Streamable HTTP, stateless, JSON responses only. There is no SSE stream and no sessions. It answers initialize, tools/list, tools/call and ping, and returns empty lists for resources and prompts.
There are 12 tools, and none of them is a generic "call any endpoint" tool:
-
Read (8):
get_business,list_jobs,get_job,find_customers,get_customer,list_invoices,get_invoice,list_services. -
Write (4):
create_customer,update_customer,request_job,add_note.
Each tool calls the same handler as our public REST API, with the caller already checked. Business isolation, rate limits and plan checks therefore exist in exactly one place:
const presetContexts = new WeakMap<Request, ApiContext>();
export function presetApiContext(request: Request, ctx: ApiContext): Request {
presetContexts.set(request, ctx);
return request;
}
// inside the REST wrapper
const ctx = presetContexts.get(request) ?? (await authenticateApiCall(request));
Annotations matter more than you think
Both directories read tool annotations:
-
readOnlyHint: trueon the eight reads lets them run without a confirmation prompt. -
destructiveHintmeans "may overwrite or delete", not "writes". Our create, note and job-request tools only add data, so they keepfalse.update_customeroverwrites fields, so it getstrue. - Tool descriptions must not tell the model to call other tools. We had "For today's schedule pass the date from get_business" in one description and removed it. Claude's review criteria refuse that pattern.
OAuth: discovery, DCR and PKCE
An unauthenticated call gets a 401 whose WWW-Authenticate header points at the protected resource metadata (RFC 9728):
WWW-Authenticate: Bearer resource_metadata="https://www.smarfle.com/.well-known/oauth-protected-resource/api/mcp"
That document names the authorization server. Its RFC 8414 metadata advertises:
- dynamic client registration (RFC 7591);
-
code_challenge_methods_supported: ["S256"]; - a token endpoint that rotates refresh tokens.
The authorization endpoint is a normal page in our app, where the business owner or a manager approves the assistant and chooses read-only or read and write. Tokens are stored only as SHA-256 hashes. An access token lasts an hour and is refused as soon as the person who approved it is no longer an owner or manager of that business.
Bug 1: rate limits keyed by IP
Our registration endpoint allowed 20 registrations an hour per IP, and the token endpoint 30 requests a minute per IP. That's sensible for the open internet, and wrong for AI platforms. Claude registers one OAuth client per user from Anthropic's published egress range (160.79.104.0/21). Every Claude user would have shared one bucket.
The fix:
- requests from that range share a platform-wide registration budget;
- token requests from that range are counted per client;
- everyone else is still limited per IP, so nobody can dodge the limit by inventing client ids.
Bug 2: ChatGPT and the 500-character state
Claude connected on the first try. ChatGPT failed with:
MCP authorization failed: OAuth completion failed: Unterminated string in JSON at position 353
Our server issued the code every time, and ChatGPT never redeemed it. The cause was one line in our authorize parser:
const state = (get("state") || "").slice(0, 500);
Claude's state is a short random string. ChatGPT's is a long base64-encoded JSON object. We trimmed it, sent it back, and ChatGPT could no longer decode its own state.
Lesson: state is opaque. Return it byte for byte, cap its size, and refuse anything over the cap rather than trimming it.
Bug 3 (not a bug, a feature): RFC 9207 iss
ChatGPT uses a stable redirect URI (https://chatgpt.com/connector_platform_oauth_redirect) only if the authorization server:
- returns
issin every authorization response; - advertises
authorization_response_iss_parameter_supported: true.
Otherwise it falls back to a per-connection callback URL. Adding iss was two lines, and it protects against authorization-server mix-up attacks too.
Testing
We run a live end-to-end script against production after every change to this code. It registers a client, approves as a demo business owner, exchanges the code and checks that the code works only once. It also lists the tools, checks that another business's customer returns "not found", rotates the refresh token, checks that the old tokens fail, revokes, and cleans up. It currently runs 28 checks.
Try it
The server is listed in the official MCP Registry as com.smarfle/smarfle. It connects with any MCP client that supports OAuth at https://www.smarfle.com/api/mcp. The setup guide is at smarfle.com/docs/claude, and the REST API it wraps is documented at smarfle.com/docs/api.
If you're building a remote MCP server, the one thing to remember is to test with both Claude and ChatGPT before you ship. They exercise different parts of OAuth.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.