For years, every app that signed users in to Needl was one we built and registered ourselves. Then Claude and ChatGPT showed up, knowing nothing about us except a URL.
One question in Claude and ChatGPT
We asked Claude and ChatGPT, through the Needl connector, what is driving Nvidia's data center revenue growth in the latest quarter. ChatGPT answered the same question through the same connector.
Behind both answers is one MCP server codebase. It runs as several deployments, each with its own tools and sign-in. Our first MCP server took a bearer token in a header and streamed over SSE. This post covers what it became.
What each deployment needed
The Model Context Protocol (MCP) is an open standard for connecting a service to an AI assistant. A server exposes tools, the assistant decides when to call them, and the user signs in once. Our server had to cover several Needl deployments.
- Different products. Each deployment has its own server name, logo, tool names and tool descriptions.
- Different capabilities. One deployment offers report generation and another doesn't. One connects to the apps a user has linked, and another hides web search.
- Different sign-in requirements. Each deployment signs users in through its own identity provider, and not every provider supports what MCP clients expect.
- Any MCP client. Claude and ChatGPT first, and whatever connects next.
A fork per deployment would have copied the same tools, auth and plumbing again and again, and the copies would drift apart. So we kept one codebase and moved every difference into config.
Three deployments, one codebase
One codebase becomes a separate server per deployment, set by config
Shared code
Per-deployment config
What the assistant connects to
- All tools, each tagged
- Two sign-in modes
- Middleware and storage
- Built on FastMCP
Tags: user chat integrations
Answers: full citations
Own name, logo and tools
Own sign-in mode
Tags: user chat reports
Web search: hidden, tools renamed
Own name, logo and tools
Own sign-in mode
Tags: user chat integrations
Answers: compact
Own name, logo and tools
Own sign-in mode
The rest of the post uses Needl (production) and Customer 1 from Figure 2 as examples. A separate setting chooses each deployment's sign-in mode.
One codebase, configured per deployment
The server is built on FastMCP, a Python framework for MCP servers. The design has three parts. Tools are written once and tagged, each deployment has a config entry, and a startup step turns the two into the server an assistant sees.
Tools are written once and tagged
Every tool declares which group it belongs to. Most tools know nothing about which deployments will expose them.
@mcp.tool (
name="list_report_types",
title="List Report Types",
tags={"reports"},
description="List available report types that can be generated. ...",
annotations={
"title": "List Report Types",
"readOnlyHint": True,
"idempotentHint": True,
},
)
async def list_report_types(ctx: Context) -> ReportTypesResponse:
...Every tool returns a typed model, goes through one shared HTTP client with timeouts, and is wrapped in one error handler. Adding a tool means following those rules and choosing a tag.
A deployment is a config entry
Everything that differs between deployments sits in one dictionary entry, picked at startup by an environment variable. This is Customer 1 from Figure 2. The name is made up, and the keys are real.
MCP_CONFIG = {
"customer_1": {
"server_name": "Customer 1 Research",
"icon": "customer_1.png",
"include_tags": {"user", "chat", "reports"},
"hidden_args": {"web_search"},
"tool_overrides": {
"ask_needl": {"name": "ask_customer_1", "title": "Ask Customer 1", "description": "..."},
},
"instructions": "Use `ask_customer_1` for research questions ...",
},
}| Setting | What it controls |
|---|---|
include_tags | Which groups of tools are visible. Anything outside the list is hidden. |
tool_overrides | Tool names, titles and descriptions, so each product speaks in its own words. |
hidden_args | Arguments this deployment never exposes. Each one must have a safe default. |
compact_result | Whether answers come back with full citations or a compact list of sources. |
server_name, icon, instructions | What the assistant sees when it first connects, including when to use which tool. |
The tools each deployment exposes
At startup the server registers every tool, then narrows and reshapes them for the active deployment. FastMCP filters tools by tag and transforms their argument schemas without touching the tool code. Needl (production) and Customer 1 end up with different tool lists.
| Tool group | Needl (production) | Customer 1 |
|---|---|---|
| Account | who_am_i | who_am_i |
| Research | ask_needl, get_ask_needl_result | ask_customer_1 (renamed), get_ask_needl_result |
| Web search | Exposed as an argument | Hidden |
| Reports | Not exposed | list_report_types, report_chat, get_report_status, get_report |
| Connected apps | list_integrations, get_integration_accounts | Not exposed |
A hidden argument disappears from the schema the assistant sees, and the tool runs with its default. On the MCP side, adding a deployment takes a config entry and a logo.
We apply renames when a tool is declared, and hide arguments through a transform. Claude's connector directory expects a tool's title inside its annotations, and a transform can rename a tool but can't set its annotations. Reading the override at declaration keeps the name and the title in step.
The server's instructions name tools too, so they sit in the same config entry as the renames. An instruction that still names the old tool sends the model to a tool that doesn't exist.
Asking the user mid-call
Some tool calls need a choice only the user can make, such as which of their workspaces to search. The server asks with an MCP elicitation, a picker shown inside the assistant, and skips the question when there is only one option. A client that can't show a picker gets an error with next steps, so the model can ask the user itself and retry.
Sign-in for Claude and ChatGPT
In a normal web app, we register our own frontend with the identity provider ahead of time. Its client ID and allowed redirect URLs are set up once, by us. With MCP, the app signing in belongs to someone else, Claude or ChatGPT. They arrive knowing only our server's URL, so the MCP spec has them work out the rest.
Three systems take part in sign-in. Claude or ChatGPT is the OAuth client. Our MCP server exposes the tools. The identity provider authenticates the user and issues tokens.
A normal web app
With MCP
How an assistant finds its way to a login
- The assistant calls the MCP server without a token and gets a 401. The response points to the MCP server's protected-resource metadata, a small JSON document that names the server's resource identifier and the authorization server that issues tokens for it.
- The assistant reads the authorization server's metadata to find its login and token endpoints.
- The assistant identifies itself as a client. It uses a client ID registered ahead of time, publishes its details at a URL that serves as its client ID, or registers on the spot.
- The user signs in through the OAuth authorization-code flow with PKCE, the same browser flow a web app uses. PKCE lets the assistant prove it started the login, so an intercepted authorization code is useless to anyone else.
- The assistant calls tools with the access token it receives.
Step 3 supports two ways for clients to identify themselves without prior registration. With a Client ID Metadata Document (CIMD), the client's ID is a URL where it publishes its name and redirect URLs, and the authorization server fetches them. With Dynamic Client Registration (DCR), the client sends those details to a registration endpoint and gets an ID back. The 2026-07-28 MCP spec release makes CIMD the preferred registration mechanism and deprecates DCR. ChatGPT and Claude each document the options they support.
Step 3 is also where identity providers differ most. Some accept clients that identify themselves, and others only know apps an admin created by hand.
Two modes behind one switch
Each deployment picks a mode in config. The tools never know which one is running.
- Native mode
- Sign inAI assistantIdentity provider
- The provider's tokenIdentity providerAI assistant
- Tool calls with that tokenAI assistantMCP server
- Checks signature, issuer and audience
- Proxy mode
- Sign inAI assistantMCP server
- Sign in as one pre-registered appMCP serverIdentity provider
- A token the server issuedMCP serverAI assistant
- Tool calls with that tokenAI assistantMCP server
Native mode. When the identity provider supports MCP-style client registration, the server only has to be a resource server. It publishes metadata pointing assistants to the identity provider, then checks each token's signature, issuer and audience against the provider's public keys. Our backend already runs the same check for the web app.
In native mode, one early bug came from the resource identifier advertised in step 1. The assistant uses that identifier when requesting a token. The token's audience identifies the service it is intended for, and our identity provider required an exact match with its registered audience. FastMCP's default appended /mcp to the URL. Sign-in started working after we configured the advertised identifier to match the registered value.
FastMCP's default
- Advertised resource identifier
https://mcp.example.com/mcp - Registered audience
https://mcp.example.com
Not an exact match, so sign-in fails
Configured to match
- Advertised resource identifier
https://mcp.example.com- Registered audience
https://mcp.example.com
Exact match, so sign-in works
Illustrative addresses.
Proxy mode. When the identity provider can't register apps on the fly, the server acts as the authorization server itself, using FastMCP's OAuth proxy. Assistants get a full MCP sign-in from the server, and the identity provider sees one ordinary, pre-registered app. Proxy mode accepts both CIMD and DCR, because some MCP clients don't support CIMD yet.
Assistants sign in with our server, and the provider sees one known app
- 1. Identify itself (CIMD or DCR)AI assistantMCP server
- 2. Start login, with PKCEAI assistantMCP server
- 3. Consent screen
- 4. Login as one known app + PKCEMCP serverIdentity provider
- 5. Callback with a codeIdentity providerMCP server
- 6. Swap the code for tokensMCP serverIdentity provider
- 7. Our one-time codeMCP serverAI assistant
- 8. Redeem code + PKCE verifierAI assistantMCP server
- 9. Our signed tokenMCP serverAI assistant
- 10. Tool calls with that tokenAI assistantMCP server
There are two PKCE handshakes, one between the assistant and the server and one between the server and the identity provider. The assistant holds an access token the server issued, and the server manages the provider session behind it.
On every tool call, the server verifies the proxy-issued access token, retrieves the linked provider session, and validates the provider's access token. It uses the stored refresh token to renew an expired provider token. The user stays signed in while the provider accepts refresh requests. Deleting the stored session revokes access before the proxy-issued token expires.
Getting the user's identity to the tools
The tools call the Needl backend as the signed-in user, so they need the credential the backend expects. A small middleware runs on every request, reads the verified identity, and puts that credential into a request-scoped context variable. A simplified version:
class IdentityBridge(Middleware):
async def on_request(self, context, call_next):
user_credential.set(None)
access = get_access_token()
if access:
user_credential.set(backend_credential(access))
return await call_next(context) It resets the value first, so no request can see a credential left over from another. Tools read user_credential.get().
Consent and shared sign-in state
Consent. In proxy mode, any app can register itself with the server. That openness lets users connect from any client, and a consent screen guards it. Before any login starts, the server shows the app's name and where it will send the user, and the user approves it. A signed cookie ties the approval to that browser, so the login can only finish in the browser that approved it.
Shared, encrypted state. Proxy mode keeps app registrations, logins in progress and token references in a store. If that store lives in memory or on local disk, a login started on one instance fails on another, and every deploy signs everyone out.
Our store is shared, encrypted at rest and namespaced per deployment, with the key derived from a secret every instance shares. No instance holds sign-in state of its own, so users stay signed in across deploys and the service is no longer pinned to one instance.
In memory or on local disk
The login fails, and every deploy signs everyone out.
One shared, encrypted store
Users stay signed in across deploys.
Designing tools for an LLM caller
The caller of our tools is a model, and it treats every description as an instruction. It may retry when it is unsure, and it can't wait or sleep between calls. That shaped most of our tool design.
Long answers, short calls
A cited research answer can take longer than an assistant will wait for one tool call, so we split the request across two tools. The first, ask_needl, saves the question to a session, starts generating the answer and returns a session ID and request ID immediately. The backend keeps working after that call returns. The second, get_ask_needl_result, waits on the server for the answer.
for attempt in range(POLL_MAX_ATTEMPTS):
data = await get_chat_result(request_id, session_id, token, workspace)
if data.get("status") != "PENDING":
break
if attempt < POLL_MAX_ATTEMPTS - 1:
await asyncio.sleep(POLL_INTERVAL_SECONDS) Each call checks the backend up to five times, eight seconds apart, so one call sleeps at most 32 seconds. If the answer is still being generated, the tool returns PENDING, and its description tells the assistant to call again.
ask_needlReturns a session ID and request ID immediately
The backend keeps workingget_ask_needl_resultPENDINGCall againDescriptions are prompts
Tool and parameter descriptions guide the model's tool selection and arguments, so we write them as instructions.
- When to use it, and when not to. The ask tool covers research questions, and its description points the model to the report tool for reports.
- What to call next. The ask tool's description names the result tool and says to keep calling it until the answer is done.
- Pass the question through unchanged. We explicitly ask the model to preserve the user's original wording, so Needl receives the same question the user would submit in the web app.
- Make a fresh session ID. To stop models copying an example ID, the description asks for a new random UUID for each new conversation, and the same one for follow-ups.
Hints for clients
Every tool declares MCP annotations. Clients can use them as signals when deciding what to run without asking and what to retry, and each client decides how.
| Tool kind | Read-only | Idempotent |
|---|---|---|
| Lists and lookups | Yes | Yes |
| Fetching a finished answer | Yes | Yes |
| Asking a question or sending a message | No | No |
Claude

Tools that add to a conversation are deliberately not marked idempotent. A silent retry would post the same question twice.
Errors the model can recover from
The shared error handler returns every failure in the same shape, and the ones the model can fix, like a wrong argument, include the next step. When a model sends an argument the tool doesn't have, or leaves out a required one, a middleware checks the call against the tool's schema and returns the list of valid arguments, so the model can fix the call itself.
Trade-offs and limits
- Proxy mode holds refresh tokens. Users stay signed in because the server keeps their provider refresh tokens. That makes the encrypted store the most sensitive part of the service.
- Config can sprawl. Every new key adds combinations to test. Instructions have to name renamed tools, so a rename means editing two places in the entry.
- Every client feature needs a fallback. Pickers and client registration depend on what each client supports, so the server always keeps a plain path, such as an error with next steps.
What we learned
- Check the audience your framework advertises. Some identity providers match a token's audience exactly, so a default that appends a path can break every login.
- Apply renames at declaration. A directory that reads titles from annotations won't see a rename made by a transform.
- Tell the model what to generate. Don't leave IDs to chance. The description asks for a fresh UUID per conversation, never a copy of an example.
Claude and ChatGPT still arrive knowing only a URL. Config decides what they find there.
FAQ
Which assistants can connect?
MCP clients that support remote servers with OAuth sign-in should work. We built and tested against Claude and ChatGPT.
Why not a separate codebase per customer?
The copies would drift. With one codebase, every fix reaches every deployment, and a new tool reaches every deployment that includes its tag.
Does the assistant hold the identity provider's tokens?
In proxy mode, the assistant holds a token the server issued, and the provider's access and refresh tokens stay in the server's encrypted store. In native mode, the assistant holds the provider's token directly.
Try it: connect Needl to your assistant from needl.ai/platform/mcp.



From Chatbot to Context Engine: Building AskNeedl’s Remote MCP Server
Many Apps, One Workspace: How We Share Code Across 11 React Apps with Bun
One API Catalog, Many Audiences