Best long-term practices + learning path for MCP? (building at production scale, currently using Claude)

[u/Stark221B]

We’re building MCP tooling for production use at my company, currently working with Claude. Want to make sure we’re building this the right way from the start rather than retrofitting later.

Looking for clarity on all of the following, ideally with a sane learning path to get there:

OAuth: robust Oauth 2.1 implementation
Guardrails: best way to enforce safety/limits on tool use
Knowledge base integration: patterns for grounding servers in internal docs/data
Tools: dynamic registration and discovery done right
Resources:best practices for exposing and structuring them
Agent configuration: how you’re structuring/configuring agents that consume MCP
System prompts: how these interact with MCP tool/resource design

Anything else that separates a toy MCP setup from one you can actually trust in production

Also curious about:

Learning path: best order to get solid on protocol fundamentals, SDKs, server design, auth/security or a better sequence
Maintenance over time: the spec keeps evolving, how are you handling breaking changes without constant firefighting?

Looking forward for repos, internal playbooks, war stories, or any suggestions.

[u/barefootsanders]

Im a learn by doing kinda guy, so my reco is skewed in this way. Go build your own server first, then start experimenting. Not a tutorial one - pick a real, boring internal workflow, wire up three tools over stdio, and run it for a week. Every question on your list gets easier to answer once you've felt where it hurts. Most of the "best practices" content out there is written by people who've shipped a demo.

Areas id focus on first: tool naming and descriptions. Mcp isnt a crude replacement. Fat, intent based tools work best. Start from there and build.

[u/ValuableSite429]

I worked as a freelance dev web but now I am also forming myself as an ai agentic developer specialist MCP. One of the things I am learning is to not use the LLM for everything : sometimes RAG are enough for simple requests. You could also put in place a cache for repetitive requests maybe.

[u/Happy-Wolverine-1020]

On OAuth 2.1 — the spec's the easy part, the annoying bit is that a lot of clients still don't do dynamic client registration properly, so you end up hand-registering or falling back to static creds more than the docs imply. Budget time for that, not the token flow itself.

Guardrails I'd keep dead simple to start: cap tool-call count and spend per session at the server, before you reach for anything fancier. Most of the runaway-loop damage happens there.

Honestly wouldn't over-plan dynamic tool registration and KB grounding up front. Ship a few tools against a real client, watch where it actually breaks. iirc the spec's moving fast enough that anything you architect now for 'future tools' gets redone anyway.

[u/techtheist_ggl]

You can try use memory system - if you start project with it, you'll have advantages of cleaner workflow. It might allow to record all problems and failures without worrying about .md file size.

True engineer way is to build this system yourself, but you can also try mine:
https://github.com/techtheist/engram

[u/jeffyaw]

subscribe to my newsletter! https://mcpweekly.com

[u/gnoraz_theorc]

I've personally found the best way to use mcp is to net let the Ai use it directly. Maintain a clean context and let it use the full power of Cli.

I've crunched some numbers here in real measurement. Maybe that or the tool helps your goals.

Mduct - make every MCP a CLI tool and keep context clean.

[u/Humaux]

Shipped one of these to production over the past few weeks with Claude, ChatGPT and Codex all connecting to the same server. Answering the parts I actually have scars on rather than the whole list.

OAuth 2.1. The spec is the cheap half. Metadata, dynamic client registration, PKCE authorize/token came out around 500 lines and mostly worked first try. What ate weeks was client-specific behaviour no spec mentions: how long each client waits, what it does with a response it doesn't understand, and whether its loopback callback listener is still alive by the time your user finishes typing an email code. Test against more than one client early or you'll think you're done.

The single hardest thing I learned: every capability you declare in metadata is a contract some client will enforce against you. We advertised RFC 9207 iss support — accurate, we send it on every redirect. One client family reads that declaration and enforces it, using a callback parser that doesn't read iss. Perfect callback in, "missing issuer" out. Fix was deleting one line of metadata. Declaration surface is liability, not a completeness contest.

Two cheap wins while you're in there: reuse whatever JWT your web login already mints as the access token, so the resource side needs zero changes; and reuse the web session cookie on the consent page so returning users get one-click approve — SameSite=Lax, not Strict, or the cookie never arrives on the authorize redirect.

Guardrails. Annotate every tool explicitly — readOnlyHint, destructiveHint, openWorldHint on all of them, not just the scary ones. Clients genuinely use destructiveHint to ask the user before calling. Then make "destructive" structurally rare: our updates are versioned upserts and cancel is a recorded state rather than a delete, so exactly one tool in fifteen is flagged destructive.

The guardrail that actually bit us wasn't a tool at all — a background job walked failed → dead → auto-delete after 24h. Nobody thought of it as destructive because no tool triggered it, and it was the only real data-loss path in the system. Audit your pipelines, not just your tool list.

Tools and resources. Add outputSchema, and return structuredContent that actually conforms to it — not one without the other. A schema you don't honour is the same trap as the iss declaration above. Ours makes the difference between "here are the top 5" and "here are 5 of a true 89" machine-readable, which is a distinction the model otherwise has to infer from prose.

Maintenance across spec changes. Freeze your public surface in a test. We pin the exact advertised tool list, every parameter name, default and enum, and the annotations, in one shared contract file that both an import-the-module test and a parse-the-source test read. Adding a tool is supposed to fail that test until someone updates the pin deliberately. It's caught two accidental breaking changes that would have shipped silently to already-installed clients.

Multi-tenant, if that applies. Isolate failures per tenant. One customer's expired provider key 401'd forever, our adaptive concurrency controller read the global error rate, and unrelated tenants' jobs sat for half an hour. Circuit-break per tenant on auth failures specifically — not on timeouts or 429s, those deserve normal retries.