DEV Community: FP Intern

MCP for tour guides: building a remote MCP server with ~100 tools and OAuth

FP Intern — Sat, 03 Oct 2026 10:30:05 +0000

I work on Your Next Tours, an app tour guides use to broadcast live audio to their group from their phone. Guests scan a QR code and listen in the browser. Before a tour, guides prepare a lot of material in our panel: day-by-day programs, stops, info cards, guest lists, sometimes a small company website.

Most of that material already exists somewhere else, usually as a PDF itinerary. So we built an MCP server that lets a guide connect their own Claude, ChatGPT or Cursor to their account. The guide drops the PDF into the chat, and the model builds the program through tools instead of the guide retyping it.

This post covers how the server is set up and the problems we ran into, with the code we ended up with. Most of it applies to any remote MCP server with real user data behind it.

The setup

Endpoint: https://api.yournext.tours/api/mcp/guide
Transport: Streamable HTTP, stateless (no sessions, so it runs fine on a PM2 cluster)
Auth: OAuth 2.1 + PKCE for claude.ai and ChatGPT, or a personal API key for clients that only send headers
Authorization server: self-hosted Ory Hydra. Hydra delegates login and consent back to our existing account system, so passwords, Google/Apple sign-in and 2FA stay where they were. We decided early not to write our own OAuth server.
Registry name: tours.yournext/guide
About 100 tools, each behind a scope

The LLM cost is on the user's own subscription, which is part of why this was worth doing for us: our in-app assistant runs on our bill, this one doesn't.

1. Answer GET with 405, not 404

With a stateless server there is no SSE stream, so we had no GET handler and Fastify returned 404. Cursor and Gemini CLI showed that as "Failed to open SSE stream" and treated the server as broken.

The MCP SDK client treats 405 as "this server has no stream, carry on". So the fix is an explicit 405 for GET and DELETE:

// Stateless Streamable HTTP: no SSE stream and no sessions.
// The SDK client only treats 405 as "no stream, fine"; 404 surfaces as an error.
for (const method of ["GET", "DELETE"] as const) {
  app.route({
    method,
    url: "/api/mcp/guide",
    handler: async (_request, reply) =>
      reply
        .code(405)
        .header("Allow", "POST")
        .send({ error: { code: "METHOD_NOT_ALLOWED", message: "Use POST" } }),
  });
}

2. The 401 has to be a real 401

Claude discovers your authorization server from the WWW-Authenticate header on a 401. A few details mattered:

The status code must be 401. The same header on a 200 is ignored.
Include scope in the challenge. Without it the client requests everything in scopes_supported.
Only send the challenge when OAuth is actually configured. Pointing a client at a metadata document you don't serve makes it fail with "server unreachable".

export function unauthorizedChallenge(): string {
  const parts = [
    `resource_metadata="${headerSafe(resourceMetadataUrl())}"`,
    `scope="${headerSafe(OFFERED_SCOPES.join(" "))}"`,
  ];
  return `Bearer ${parts.join(", ")}`;
}

One more: validate the token's sub before it reaches the database. Hydra subjects are free text. A malformed one reached Postgres as a UUID cast error, came back as a 400, and since the client never saw a 401 it never started re-authorization.

3. Some clients take scopes from the authorization server, not from you

We serve RFC 9728 resource metadata with a deliberately narrow scopes_supported: read/write for tours, content, trips and the website. Scopes that expose guest PII or send email to guests are left out on purpose.

Gemini CLI ignored that document. It built its scope request from scopes_supported in the authorization server's openid-configuration. Hydra's default there is roughly openid offline offline_access, so the consent screen came up with nothing to grant and no usable token was issued.

The fix is configuration, not code: keep the AS's advertised scopes identical to your resource metadata (plus offline_access). Don't advertise the full catalog either. Consent screens usually pre-check every requested scope, so the PII scopes would be one click away from going to the LLM.

Two related Hydra settings that cost us time:

With strategies.scope: exact, a dynamically registered client that didn't pass scopes at registration gets locked to the default set, and later asks for website:write fail with invalid_scope. Set oidc.dynamic_client_registration.default_scope to the full catalog.
Hydra doesn't serve /.well-known/oauth-authorization-server (RFC 8414). SDK clients fall back to OIDC discovery, but a strict RFC 8414 client won't. We proxy that path to openid-configuration in nginx.

4. Make write tools declare their annotations

Claude's and ChatGPT's directory reviews check title, readOnlyHint and destructiveHint on every tool, and clients use them to decide when to ask for confirmation.

The spec's default for a missing destructiveHint is true. Our first version filled in false when it was missing, which meant a forgotten annotation quietly marked a delete tool as harmless. We changed it so that forgetting one fails to compile:

type WriteAnnotations = Required<
  Pick<ToolAnnotations, "destructiveHint" | "openWorldHint">
> &
  Pick<ToolAnnotations, "idempotentHint">;

interface ReadTool extends ToolBase {
  access?: "read";
  annotations?: never; // read tools are always readOnly, no overrides
}

interface WriteTool extends ToolBase {
  access: "write";
  annotations: WriteAnnotations; // no annotations, no compile
}

type Tool = ReadTool | WriteTool;

readOnlyHint is derived from access, so the two can't disagree. Because types can be bypassed with a cast, a boot-time assert checks the same thing at runtime, and a golden test pins every tool's annotations.

Our rule for destructiveHint: true: anything that deletes, overwrites or clears existing data, changes something public (publishing the website), sends something to other people, or invalidates a link that was already shared. Adding, reordering and duplicating are not destructive.

5. Scopes per tool, including reads

Every tool requires a scope, reads included. A key with only tours:read doesn't just get denied on write tools, it doesn't see them in tools/list at all. That cuts down on the model trying things it can't do.

Two decisions we'd make again:

Edits never notify guests. trips:write can change a trip, its stops and the guest list, and it never sends a notification. Delay and cancellation announcements, which email guests, need a separate trips:announce scope. A model fixing ten stops in a row can't send ten emails, and there's no way to cancel a trip silently: cancelling means announcing it.

The guest list is masked by default. Reading a trip roster sends personal data to a third-party LLM provider. Most questions ("how many people joined?") don't need it, so the default response is masked:

maskName("Ahmet Yilmaz");    // "A*** Y***"
maskEmail("ahmet@gmail.com"); // "***@gmail.com"
maskPhone("+905551234567");   // "***4567"

To be clear, this isn't access control. A client with the roster scope can pass full: true. The point is that pulling full PII becomes an explicit choice that shows up in the audit log, not something that happens by accident.

6. Tell the model who it's talking to

Tools are filtered by scope, organization role and plan. When an organization tool was missing from the list, the model made up a reason for it. Now the server puts the account, organization, role, plan and granted scopes into the instructions field of the initialize response, along with a rule not to invent URLs (published sites only live at <subdomain>.yournext.tours). With that, the model can give the actual reason instead of guessing.

7. Models fill empty fields with fiction

Asked to "build my company website", a model filled every section with made-up content without asking a single question. The fix was to make the data tell the model what to ask. get_website_overview now returns an assistantGuide with rules and a list of what's missing:

export interface IntakeQuestion {
  topic: string;
  ask: string;   // the question for the user, rephrased in their language
  offer: string; // what to write, and where, once they answer
}

The first rule tells the model to interview the user two or three questions at a time and not to fill those topics itself. Others forbid inventing prices, licence numbers, reviews or addresses. Those texts go to the model, so they're in English; the model asks in the user's language.

8. Errors the model can act on

Our tool errors used to be free text like "Tool error: validation.error", which told the model nothing. Now every tool error uses the same JSON envelope as our HTTP API: code, messageKey, message, details and a hint that says where in the panel the user can fix it. For example, details lists what's missing before a website can be published. With that, the model can fix the problem or explain it to the user.

Try it

If you run a tour business or just want to see how it behaves:

Add a custom connector in Claude or ChatGPT (ChatGPT currently needs a paid plan with Developer mode on).
Paste https://api.yournext.tours/api/mcp/guide.
Sign in and choose the scopes.

Setup guide: https://yournext.tours/ai-assistant-integration/

If your client breaks against it, or you've solved one of these differently, I'd like to hear about it in the comments.

How we built a verified dataset of 198 tour group headset rules

FP Intern — Fri, 02 Oct 2026 12:38:39 +0000

Museums and historic city centres keep adding rules about how a tour guide may talk to a group. Some require headsets above a certain group size, some ban loudspeakers, and some do not let an outside guide explain anything indoors. The rules live in PDFs, booking terms and city ordinances, in a dozen languages, and nobody had put them in one table.

We work on a small app for tour guides (Your Next Tours), so we needed that table anyway. This post is about how we built it, what the schema looks like, and the mistakes we tried to avoid. The result is open under CC BY 4.0 on Hugging Face and Kaggle.

Start wide, then throw things away

The first pass was a survey of 228 candidate rules. That list was useful for finding places, but it was not trustworthy. Some entries came from travel blogs, some quoted an old version of a rule, a few were simply wrong.

So the second pass had one job: for every candidate, open the official source again and find the quoted sentence in it. We split the list into batches and let LLM agents do the opening and searching, with one strict instruction: if the sentence is not in the official text, the record is marked not-found and does not become a rule. No search engines, only the institution's own site, its PDFs, or an archived copy of that page.

Each checked record came back as a small JSON object:

{
  "id": "fr-musee-du-louvre",
  "class": "A",
  "threshold": 7,
  "thresholdCountsGuide": null,
  "devicePolicy": "own-allowed",
  "status": "in-force",
  "quote": "...",
  "quoteLang": "fr",
  "sourceUrl": "https://...",
  "verifiedAt": "2026-10-02",
  "verdict": "confirmed"
}

A build script then keeps a record only if the verdict is confirmed or changed, the class is A, B or C, the rule is in force or formally proposed, the source is https and the quote is not empty. Everything else is dropped. In the end 197 records passed, plus one Turkish rule (the National Palaces in Istanbul) that we had already documented separately, so the dataset has 198 rows from 36 countries.

Three classes, because "headset rule" means three different things

Reading the texts side by side, they fell into three groups:

A, headsets required. A written rule says guided groups must use headsets or a whisper system (66 rules).
B, loudspeakers banned. No megaphones or amplification. Headsets are not mandatory, but with a big group they are the practical way to be heard (75 rules).
C, no outside guiding inside. Only the site's own guides or audio guides may narrate indoors (57 rules).

Keeping B separate from A mattered. Many city ordinances only ban amplification, and lumping them in with headset requirements would have inflated the headline number.

The fields that took the longest to decide

threshold. Texts say "more than 10", "10 or more", "groups of 5 to 30". We store the smallest group size the rule applies to, so "more than 8" becomes 9. An empty value means every group. Where a number exists, it ranges from 3 to 26, and the most common values are 7 and 11.

threshold_counts_guide. Some texts count the guide, most say nothing. We store true, false or empty, and empty means "the text does not say". We did not guess.

device_policy. This is the field people care about most, and the one easiest to get wrong. The values are own-allowed, unspecified, institution-only, app-banned, phone-banned and headphones-banned. 132 of the 198 rules are unspecified: the text asks for headsets but does not say whose. That does not mean any device is accepted, and the dataset card says so in plain words. Only 39 rules explicitly allow a group's own system.

quote and source_url. Every row carries the verbatim sentence in its original language and the official link, so anyone can check our reading. Rights to the quoted text stay with the issuing body.

Loading it

The CSV is a single file, so plain pandas is enough:

import pandas as pd

url = ("https://huggingface.co/datasets/first-point/tour-group-headset-rules"
       "/resolve/main/data/tour-group-headset-rules-198-20261002.csv")
df = pd.read_csv(url)

print(df.shape)                       # (198, 19)
print(df["rule_class"].value_counts())

# Rules with a group-size threshold, smallest first
cut = df.dropna(subset=["threshold"]).sort_values("threshold")
print(cut[["place", "country", "threshold", "device_policy"]].head(10))

There is also a JSONL file with the same rows and typed values, which is easier to drop into a RAG index.

One source, three outputs

The same JSON fact packs feed three things: the human-readable list at yournext.tours/tour-group-headset-rules, the Hugging Face dataset and the Kaggle dataset. Each row's page_url points to its anchor on that page, so a row like fr-musee-du-louvre links straight to the Louvre entry. Generating all three from one place is the only way we found to keep the numbers from drifting apart.

What we would do differently

Write the dropping rules before collecting anything. We decided late that a quote must be found word for word, and some early candidates that "felt right" did not survive that test.
Store effective_from as a separate field from the start. 38 of the rules took effect in 2024 or later, and one more (canal boats in Bruges) starts in 2029. That trend was the most interesting finding, and it was almost invisible in the first draft.
Plan for updates. Rules change; we will re-check the sources every quarter and publish a new snapshot.

If you know a rule we missed or read wrong, the comments here are a good place for it. We would rather fix a row than defend it.