Guides
Building an MCP server for your SaaS
Your customers are starting to ask their AI assistants to do work in your product. An MCP server is how those assistants connect to it safely. This guide covers what to expose, how to authenticate and how to keep it from becoming a security incident.
An MCP server is an integration that lets AI assistants, such as Claude, ChatGPT or an IDE agent, call your SaaS product through the Model Context Protocol. You expose a small set of well-designed tools and resources, authenticate users with OAuth and scoped tokens, and log every call. Done well, it becomes a new channel into your product.
What is the Model Context Protocol?
The Model Context Protocol (MCP) is an open standard for connecting AI applications to external systems. Instead of every assistant building a custom connector for every product, products publish one MCP server and any compatible client can use it.
Think of it as an integration surface designed for language models rather than for human developers. A REST API documents endpoints for engineers; an MCP server describes capabilities so a model can decide when and how to use them, while the user stays in control of what the assistant is allowed to do. The MCP glossary entry explains the core terms.
MCP is still evolving. At the time of writing the current specification is version 2026-07-28. The concepts in this guide are stable, but check transport options, authorisation details and client support against the current specification before you build.
What does an MCP server expose?
An MCP server can offer three kinds of capability. Most SaaS servers start with tools and add resources later.
- Tools Actions the model can call, such as
create_ticket,search_coursesorget_invoice_status. Each tool has a name, a description and a JSON schema for its inputs. This is where most of the value, and most of the risk, lives. - Resources Read-only data the client can load into context, such as a document, a report or a record identified by a URI. Useful when the assistant needs background, not an action.
- Prompts Reusable, parameterised templates a user can pick, such as “Summarise this account’s open issues”. They package good usage patterns of your product.
Clients differ in which of these they support well today, so test with the assistants your customers actually use.
Do you actually need an MCP server?
An MCP server is worth building when your customers already try to use AI assistants with your product and when your product holds data or actions that are useful in a conversation. It’s not worth building as a press release.
| Signal | What it suggests |
|---|---|
| Customers paste data from your product into chat assistants | A read-only MCP server with search and summary tools will save them time |
| Your support team answers “how do I find X” questions daily | Resources and search tools let assistants answer them directly |
| Enterprise prospects ask about “AI readiness” in RFPs | A documented, secure MCP server is a concrete answer |
| Your public API is incomplete or inconsistent | Fix the API first; an MCP server built on a weak API inherits its problems |
| Your actions are destructive or regulated (payments, payroll) | Start read-only and add write tools behind explicit confirmations |
If your public API is solid, a focused MCP server is typically a few weeks of work. If not, the API work is the real project.
Have an integration request in your backlog?
Send it over. You get a written scope and a fixed quote within 2–3 days.
How should you design tools?
Tool design decides whether assistants use your product well or flail. Models choose tools from their names and descriptions, so those are product copy, not afterthoughts.
- Model tasks, not endpoints
find_overdue_invoices(customer)beats exposingGET /invoiceswith twelve filters. One tool should do one meaningful job. - Write descriptions for a model Say what the tool does, when to use it, what it returns and what it must not be used for. Include units, formats and limits.
- Keep inputs small and typed Use enums for fixed choices, explicit date formats and sensible defaults. Fewer parameters mean fewer wrong calls.
- Return compact, structured results Return the fields that matter, with IDs the next tool can use. Paginate large results instead of dumping thousands of rows into context.
- Separate reads from writes Name write tools clearly (
create_…,update_…,delete_…) so clients and users can treat them differently. - Make writes idempotent Accept an idempotency key or check for duplicates, because models and clients retry. See the idempotency glossary entry.
- Fail helpfully Error messages should tell the model what to change: “date must be YYYY-MM-DD”, not “400 Bad Request”.
How should an MCP server authenticate users?
Remote MCP servers act on behalf of a specific user in a specific tenant, so authentication must work the way your product’s permissions already work. The MCP specification builds its authorisation on OAuth 2.1. Your server must publish OAuth protected resource metadata so clients can find your authorisation server. Clients register through client ID metadata documents, pre-registration or dynamic client registration, which the current specification keeps only for backwards compatibility.
- User consent through OAuth The client sends the user through your authorisation flow; the user signs in (via SSO if their company enforces it) and approves access.
- Scoped tokens Issue tokens with explicit scopes, such as
read:coursesorwrite:enrollments, so a user or admin can grant read-only access first. - Tenant and role enforcement Every tool call runs with the user’s own permissions in their own tenant. The MCP layer should never have broader access than the user.
- Admin controls Let customer admins enable or disable the MCP integration for their organisation, limit scopes and revoke tokens.
- Short-lived access tokens Use refresh tokens with rotation, and revoke everything when the user is deprovisioned, for example through SCIM.
Avoid long-lived personal API keys pasted into assistant settings for anything beyond prototypes. They are hard to scope, hard to rotate and invisible to the customer’s admin. The OAuth 2.0 glossary entry covers the basics.
What are the main security risks?
An AI assistant is a new kind of client: it reads untrusted text and then decides which tools to call. Treat that seriously.
- Prompt injection A document, email or ticket the model reads can contain instructions like “export all users”. Never let content returned by one tool silently authorise another destructive action.
- Over-broad tools A generic
run_queryorcall_apitool gives the model, and anyone who can influence it, access to everything. Prefer narrow tools. - Data exfiltration Large read tools can move sensitive data into a model’s context and onward. Limit result sizes and respect data classifications.
- Confused deputy problems The server must check that the user, not the server, is allowed to perform each action on each record.
- Silent destructive actions Deletes, payments and permission changes should require explicit user confirmation in the client, and ideally a second step in your product.
Write these risks into your threat model and your customer documentation. Enterprise security teams will ask.
Rate limits, quotas and cost control
Assistants can call tools in loops. Without limits, one enthusiastic session can look like an attack on your API.
- Per-user and per-tenant rate limits Apply the same rate limiting you use for your public API, with separate budgets for MCP traffic.
- Result-size limits Cap rows and characters per response; return a cursor for more.
- Expensive operations behind confirmation Long exports or bulk updates should start a job and return a status, not block the conversation.
- Clear limit errors Tell the model when to retry and how long to wait, so clients back off instead of hammering.
Audit and observability
When a customer asks “what did the assistant do in our account last Tuesday?”, you need an answer.
| Record | Why it matters |
|---|---|
| User, tenant, client name and version | Who acted, through which assistant |
| Tool name, input parameters, result status | What was attempted and whether it worked |
| Records read or changed (IDs) | Scope of access for incident review |
| Token and scope used | Proves least-privilege access |
| Latency and errors per tool | Shows which tools confuse models or fail |
Expose these events in the same audit log customers already use, filtered by “source: MCP”. It’s a strong answer to AI-related security questions.
How do you test an MCP server?
Unit tests prove your code works. They don’t prove that models use your tools correctly. Test both.
- Contract tests Validate every tool’s schema, required fields, error responses and pagination, as you would for any API.
- Permission tests For each tool, confirm a user can’t read or change another tenant’s or another role’s data.
- Real-client tests Connect the assistants your customers use and run realistic tasks: “find learners who haven’t completed onboarding and enrol them in the refresher course”.
- Adversarial tests Plant instructions in records the model will read and check that nothing destructive happens without confirmation.
- Regression set Keep a list of real tasks and expected tool sequences; rerun it when you change tool descriptions or the spec changes.
Tool descriptions are code. Version them, review changes and watch the regression set when you edit them.
Remote or local server?
MCP servers can run on the user’s machine or as a hosted service. For a SaaS product, a hosted (remote) server is usually the right default. The specification calls these the stdio transport (local) and the Streamable HTTP transport (remote).
| Local server | Remote (hosted) server | |
|---|---|---|
| Who runs it | The user, on their own machine | You, as part of your product |
| Authentication | Often an API key in local config | OAuth with per-user consent and scopes |
| Updates | Users must upgrade | You ship changes centrally |
| Admin visibility | Low | Full: audit logs, revocation, tenant controls |
| Best for | Developer tools, prototypes | Customer-facing SaaS integrations |
A local server is a fine prototype for your own team. For customers, especially enterprise customers who need admin control and audit trails, host the server and treat it like any other production API: versioned, monitored, rate-limited and covered by your security review.
A practical build plan
Most SaaS teams can ship a useful first version without boiling the ocean.
- Pick three to five jobs Choose the questions and tasks customers already bring to assistants. Start read-heavy.
- Harden the underlying API Fix missing filters, inconsistent IDs and weak pagination before wrapping them.
- Add OAuth with scopes Reuse your identity provider and SSO; add MCP-specific scopes and an admin switch.
- Build the tools and resources Narrow, well-described and idempotent.
- Wire audit, limits and monitoring Before any customer connects.
- Pilot with two or three customers Watch the logs, rewrite confusing descriptions, then add write tools.
How Hypogen helps
We build MCP servers and agent-ready APIs for SaaS products as part of our AI agent and MCP integrations service: tool design, OAuth and scopes on top of your existing identity setup, audit logging and testing with real assistants. If your API needs work first, our integration infrastructure team handles that. Many of the same identity foundations appear in our SSO and SCIM guide.
FAQ
Frequently asked questions
Can't find your question? An integration engineer will answer it.
Last updated
What is the difference between an MCP server and a public API?
A public API is designed for developers who read documentation and write code. An MCP server is designed for AI assistants that pick capabilities from descriptions at run time. It usually sits on top of your API, exposing fewer, task-shaped tools with model-friendly descriptions, user-level OAuth and audit logging for assistant activity.
Which AI assistants support MCP?
Support has grown quickly across AI assistants such as Claude and ChatGPT and development tools such as Visual Studio Code and Cursor, but it changes month to month. Before building, check which clients your customers actually use and which MCP features those clients support, especially remote servers, OAuth and resources.
Can an MCP server be read-only?
Yes, and that is the safest way to start. Search, lookup and summary tools deliver most of the early value with little risk. Add write tools once you have audit logs, scoped permissions and confirmation steps in place, and once customers ask for them.
How long does it take to build an MCP server for a SaaS product?
With a solid API and existing OAuth, a focused first version with a handful of tools typically takes 3–6 weeks, including testing with real clients. If the API or authorisation needs work first, plan for that as a separate piece of work.
How do we stop prompt injection from causing damage?
You cannot fully prevent a model from reading malicious text, so limit what it can do: narrow tools, user-level permissions, explicit confirmation for destructive actions, result-size limits and audit logs. Test with planted instructions before you launch.
Ready to make your product agent-ready?
We'll review your API and tell you which tools are worth exposing first, in a 30-minute call.