MCP Servers in Production: Lessons Learned and Pitfalls to Avoid

6 months of MCP in production: what I learned

Since January 2025, I've been using MCP servers in production in two distinct contexts: managing the EQUANS Site Factory project and consulting assignments for Swiss SMEs. Here's an unfiltered lessons-learned report.

What exceeded my expectations

Eliminating manual context

Before MCP, every Claude work session required copying and pasting project context (backlog, recent decisions, technical constraints). With the Jira MCP server connected, Claude accesses data in real time. No more manual context updates.

Contextual documentation generation

The command "generate the production release documentation for ticket EQUANS-347" now produces a complete document in 30 seconds, based on the actual ticket content, comments, and linked change history.

Pitfalls I hadn't anticipated

Pitfall 1 — MCP response verbosity

Some MCP servers return very large JSON payloads. If Claude receives an entire Jira project with 500 tickets to answer a question about 3 specific tickets, you're wasting tokens and degrading performance. Solution: design your MCP servers with built-in filters and pagination limits.

Pitfall 2 — Expired API token handling

MCP authentication errors during sessions are poorly readable. Build explicit error handling into your server that returns a clear message: "Jira API token expired — please renew your credentials."

Pitfall 3 — Overly broad permissions

During testing, I had granted Claude write access to Confluence. During a mishandled interaction, it modified a page shared with the client. The lesson: always start read-only. Add write permissions progressively, with guardrails.

Pitfall 4 — MCP call latency

Each MCP call adds latency: network + server processing + parsing. On a complex workflow with 8–10 sequential MCP calls, cumulative latency can exceed 15–20 seconds. Optimise by parallelising independent calls.

Recommendations for your deployments

• Start read-only, evaluate for 2 weeks before enabling writes
• Log everything: every MCP call, with timestamp, tool called, parameters, result
• Define rate limits: protect your source APIs from excessive calls
• Document exposed tools in clear natural language — that's what Claude "sees"
• Test error cases as thoroughly as nominal cases