When You Need a Custom Server
The public MCP server ecosystem covers popular services like GitHub, Slack, databases, and cloud providers. But every company has internal APIs that aren't covered: your deployment system, your feature flag service, your internal user management tool, your custom billing API. If you want your AI assistant to interact with these, you'll need a custom MCP server.
The good news is that MCP servers aren't complex. At their core, they're thin wrappers that translate between the MCP protocol (tool definitions and tool calls) and your API's HTTP endpoints. If your API has a REST interface, you can usually build a working MCP server in an afternoon.
Server Structure
An MCP server has two main responsibilities: declaring what tools are available (tool definitions) and handling tool calls (executing the actual logic). In TypeScript with the official SDK, a basic server looks like: create a server instance, register your tools with their input schemas, and implement the handler for each tool.
Each tool definition needs a name, a description (this is what the AI reads to understand when to use the tool), and an input schema (JSON Schema defining the parameters). The description matters more than you'd expect. A vague description like "manages users" leads to the assistant guessing when to use it. A specific description like "creates a new user account with the given email and role, returns the user ID" gives the assistant clear guidance.
Connecting to Your API
Inside each tool handler, you make HTTP calls to your internal API. Handle authentication (API keys, JWT tokens, OAuth), format the request according to your API's expectations, parse the response, and return it in a format the assistant can understand.
For authentication, the cleanest approach is accepting credentials through the MCP server's configuration (environment variables or config file) rather than requiring the assistant to pass them with each call. This keeps secrets out of the conversation context. If your API uses short-lived tokens, the server can handle token refresh internally.
Error handling deserves attention. When your API returns a 404, don't just pass through the raw HTTP error. Return a meaningful message like "User with ID 12345 not found" that the assistant can relay to the user. Good error messages make the whole experience feel polished.
Testing and Deployment
Test your server locally first by connecting it to your AI assistant and trying real workflows. Start with read-only tools (list, get, search) before adding write operations (create, update, delete). This lets you verify the integration works without risking unintended changes.
For deployment, you've got options. Running the server locally alongside your assistant is simplest. If multiple team members need access, deploy it as a service on your internal network. Docker makes deployment predictable, and you can use the same container locally and in production. Check our guide on testing MCP server integrations for a thorough testing approach.
Sharing with Your Team
Once your server works, consider publishing it internally or even publicly if it could help others. The AI tool directories are full of servers that started as internal tools and grew into community projects. At minimum, document the setup process and tool descriptions so your teammates can get started quickly.