How to build an MCP server for your app or API

By the end of this guide you will have a working Model Context Protocol (MCP) server that exposes a few tools from your app or API, tested with an MCP client, and either running locally or hosted so other people can connect to it. MCP is the open protocol that lets AI assistants call tools and read data, and building a server means writing functions that an assistant such as Claude Code or Cursor can discover and call.

If you want to build an MCP server, the main choice is between writing it with an SDK in your language, generating it from an API you already have, and running it on a platform that handles hosting and access control. This guide covers all three and compares six tools from our Developer platforms category.

Key takeaways

• An MCP server exposes tools, resources and prompts. The usual path is to write ordinary functions with typed inputs, let an SDK generate the schemas, then test with an MCP client before you connect a real assistant.
• The main decision is the route: an SDK for Python or TypeScript (MCP Python SDK, FastMCP, MCP TypeScript SDK), a platform that turns an API into tools and hosts them (Gram), or a managed or self-hosted layer for running and governing servers (Metorial, ToolHive).
• A stdio server must not write logs to standard output, because that channel carries the protocol.
• Treat every tool as a permission. Expose the smallest set that does the job and ask for human approval before anything destructive.

What you need before you start

• An app or API to expose. Know which three to five actions or data lookups an assistant should be able to use.
• A language runtime. Python for the Python SDK and FastMCP, Node.js (or Bun or Deno) for the TypeScript SDK. The MCP Python SDK requires Python 3.11 or newer.
• An MCP client for testing. An assistant or editor that supports MCP, or the Inspector that ships with the Python SDK's command-line extra, which needs Node.js and npx.
• A decision about access. Who may connect, how they authenticate and which data they may see.
• Time. A first local server with one tool takes under an hour. Authentication, hosting and review take longer.
• Difficulty. Moderate. You write code and think about security.

Which kind of AI tool fits this job

Choose by language and by how much of the surrounding work you want to own.

An official SDK when you want direct control. The MCP Python SDK is the official Python library: you write functions with type hints and docstrings, and it generates the schemas and handles protocol details. It speaks stdio, Streamable HTTP and SSE. The MCP TypeScript SDK is the official TypeScript implementation, running on Node.js, Bun and Deno, with tool inputs declared as schemas such as Zod and adapters for Express, Fastify, Hono and Node HTTP.

A higher-level Python framework. FastMCP turns ordinary Python functions into MCP tools, resources and prompts, validates inputs and outputs, and covers authentication and OAuth support. It also has clients and apps that return forms, tables and charts. Its maker offers Prefect Horizon for deploying a server from a GitHub repository.

A platform that generates and hosts servers. Gram from Speakeasy sources tools from existing APIs or lets you write them as TypeScript functions, groups them into toolsets and exposes them as MCP servers with OAuth built in. It also offers a gateway, session logging and risk scanning.

A layer for running and governing servers. Metorial offers managed integrations, hosting for custom or Docker-based MCP servers deployed from Git hosts, per-user permissions and audit logs. ToolHive is an open-source platform that runs each MCP server in an isolated container, with a registry of vetted servers and a gateway that puts many servers behind one endpoint.

Step 1: Decide what to expose

A small, well-described tool set works better than a large one.

1. List the actions an assistant should perform and the data it should read. Start with read-only lookups.
2. Name each tool for what it does, in plain verbs, such as "search orders" or "get invoice".
3. Write a short description for each tool, because the assistant reads it to decide when to call it.
4. Mark any action that changes data or costs money, and plan a human approval step for those.

Check it worked by being able to describe each tool in one sentence and say who should be allowed to use it.

Step 2: Choose your route

You end this step with an SDK or platform picked.

1. If your codebase is Python, choose the MCP Python SDK or FastMCP. If it is TypeScript, choose the MCP TypeScript SDK.
2. If you already have an API specification and want tools generated quickly, look at Gram, which sources tools from existing APIs.
3. If you need hosting and access control for many servers, compare Metorial and ToolHive in the table below.
4. Note version risks. The Python SDK's v2 has breaking changes from v1, and the TypeScript SDK's v2 ships as separate packages that replace the single v1 package, so pin versions deliberately.

Check it worked by confirming your language, runtime version and hosting needs match the tool you picked.

Step 3: Write your first tool

The aim is one working tool that an assistant can call.

1. Install the SDK. The Python SDK installs from PyPI as mcp, and the TypeScript SDK installs from npm.
2. Define a function with typed inputs and a clear docstring or description. The Python SDK and FastMCP generate schemas from type hints, and the TypeScript SDK validates inputs against Zod schemas before your handler runs.
3. Register the function as a tool on the server object, then add a resource or prompt only if you need one.
4. Return structured, concise results rather than huge payloads, to protect the model's context.

Check it worked by calling the function directly in a test and getting the output you expect.

Step 4: Run the server locally and test it

Test with a client before you connect a real assistant.

1. Start the server over stdio for local use. For a stdio server, log to stderr, because stdout carries the protocol.
2. Use the Inspector for testing. The Python SDK's command-line extra includes a mcp dev command and an Inspector, which needs Node.js and npx.
3. Call each tool with valid, invalid and empty inputs, and read the error messages.
4. Connect a real MCP client such as an editor or coding agent and ask it to use the tool in plain language.

Check it worked by seeing the client list your tools and call one successfully from a natural-language request.

Step 5: Connect it to your real app or API

Now wire the tools to real data, carefully.

1. Call your existing API or database from inside each tool function, using a dedicated credential with the least access needed.
2. Validate inputs again on the server side. Never pass assistant-generated text straight into a query or command.
3. Handle errors by returning clear messages, not stack traces with secrets.
4. If an API specification already exists, consider generating tools from it with a platform such as Gram instead of hand-writing wrappers.

Check it worked by running an end-to-end request that reads real data and confirming nothing outside the tool's scope is reachable.

Step 6: Add authentication and choose a transport

Local stdio is fine for you; shared servers need access control.

1. Use Streamable HTTP for remote servers. The Python SDK supports stdio, Streamable HTTP and SSE, and the TypeScript SDK supports stdio and Streamable HTTP.
2. Add authorisation. The Python SDK has OAuth token handling built in, FastMCP lists authentication and OAuth support, and Gram lists OAuth built in for its hosted servers.
3. Decide per-user permissions. Metorial lists allow or deny access per group on each integration and audit logs, with access management and SAML SSO on its Enterprise plan, and ToolHive lists centralised authentication, authorisation and tool filtering through its gateway.
4. Limit who can reach the server at the network level as well.

Check it worked by connecting as an authorised user and as an unauthorised one, and confirming only the first succeeds.

Step 7: Deploy, observe and review

Put the server where users can reach it, and watch how it is used.

1. Pick a host. FastMCP's maker lists Prefect Horizon, which deploys from a GitHub repository, Gram offers serverless hosting for MCP servers, Metorial hosts custom or Docker-based servers, and ToolHive can run servers in containers on your own infrastructure.
2. Turn on logging and tracing. The Python SDK has built-in OpenTelemetry spans, and Gram and Metorial describe logs, tracing or audit trails of tool use.
3. Review which tools are used, which fail and which are never called, and trim the set.
4. Re-test after each SDK or client update, since the protocol and SDKs are changing.

Check it worked by seeing a real tool call from a deployed server appear in your logs with the caller identified.

Tools for this job compared

Tool	Good fit for	Pricing	Stated limits
MCP Python SDK	Official Python servers and clients	Open source	Needs Python 3.11 or newer; v2 breaks from v1; Inspector needs Node.js and npx; not a hosted service
FastMCP	Python servers, clients and apps from plain functions	Open source	Requires Python; TypeScript users need a separate project; Horizon needs a GitHub repository
MCP TypeScript SDK	Official TypeScript servers on Node.js, Bun and Deno	Open source	v2 replaces the single v1 package; stdio servers must log to stderr; not a hosted service
Gram	Generating, hosting and governing MCP servers from APIs	Free trial, paid from $0.35, usage-based (checked 24 Oct 2026)	Pay as you go bills three metered products plus inference at provider cost; SSO and full audit trail are Enterprise
Metorial	Managed integrations, custom server hosting and per-user access	Freemium, paid from $250/mo (checked 24 Oct 2026)	Dev plan: 1 project, 2 team members, 10 provider integrations; production starts on Scale
ToolHive	Running MCP servers in containers on your own infrastructure	Open source	Okta and Entra ID, hardened images and SLA support are Stacklok Enterprise; community support otherwise

Prices and plan limits change, so confirm the current terms on each vendor's site before you commit.

Common mistakes to avoid

• Exposing too many tools. A long tool list confuses the assistant and widens your attack surface. Fix it by starting with a few read-only tools and adding more only when needed.
• Vague tool descriptions. The assistant chooses tools from their descriptions, so unclear text leads to wrong calls. Fix it by writing short, specific descriptions and testing with natural-language requests.
• Writing logs to standard output on stdio. It corrupts the protocol stream. Fix it by logging to stderr, as the TypeScript SDK's listing advises for stdio servers.
• Trusting assistant-supplied input. Text generated by a model can contain injected instructions or unsafe values. Fix it by validating inputs on the server, using least-privilege credentials, and requiring human approval for destructive actions.
• Pinning nothing. SDKs have had major version changes, and documentation can describe features not yet released. Fix it by pinning versions and reading the migration notes before upgrading.

How we put this together

This is an evidence-based guide built from each tool's listing in our directory, which is compiled from the vendor's own site and pricing page. It is not a review based on using the tools. We don't rank tools, and nobody paid to be included. Some outbound links may be affiliate links; see our disclosure.

Frequently asked questions

Can I build an MCP server for free?

Yes. The MCP Python SDK, the MCP TypeScript SDK, FastMCP and ToolHive are free, open-source projects, and FastMCP's Horizon hosting is free for personal projects. Gram and Metorial have paid or usage-based plans for hosting and governance, and Metorial lists a free Dev plan.

What language should I use?

Use the language your API or app is already written in. The official SDKs cover Python and TypeScript, and FastMCP is a Python framework. If you do not want to write wrappers by hand, a platform such as Gram can source tools from an existing API.

Is an MCP server safe?

It is as safe as the tools you expose. Give each tool the least access it needs, authenticate callers, validate inputs, log usage and require human approval before actions that change data or spend money. Review the setup with your security team before connecting production systems.

How is MCP different from a normal API?

An API is built for developers to call with code. An MCP server describes tools in a standard way so an AI assistant can discover and call them from a conversation. Many MCP servers wrap an existing API.

How long does it take to build one?

A local server with one tool is the quick part, since the SDKs generate the schemas and protocol handling for you. Authentication, hosting, testing and a security review usually take longer than the first prototype.

Compare more options in our Developer platforms category.