Build a Custom MCP Server

What you'll learn

How to design MCP tool schemas with Zod input validation
How to scaffold and generate an MCP server using Autohand and the TypeScript SDK
How to test your MCP server locally and register it in your Autohand configuration
How to share your MCP server with your team and extend it with new tools

Before you start

Autohand Code installed
Node.js 18 or newer (required by the MCP TypeScript SDK for native fetch support)
Basic TypeScript familiarity (the MCP SDK is TypeScript-first and uses Zod schemas)
An internal API or data source to wrap, with its base URL and authentication method
An existing Autohand config file at ~/.autohand/config.json (see the MCP servers guide)

Tip: If you have an OpenAPI specification for your internal API, include it in the same directory as your project before starting the session. Autohand reads it to generate accurate parameter schemas and response type definitions for each tool.

What is MCP

Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources. Instead of hard-coding specific API calls into a prompt, you write an MCP server that exposes capabilities as named tools with defined input schemas.

When Autohand connects to your MCP server, it discovers the available tools and their schemas automatically. During a session, the agent can call any of those tools, inspect the results, and use them to answer questions or complete tasks.

The architecture has three parts.

Your MCP server. A Node.js process that registers tool handlers and handles requests over stdio or HTTP.
The MCP SDK. The @modelcontextprotocol/sdk package that handles the protocol framing, tool registration, and request routing.
Autohand as the MCP client. Autohand discovers your server via its configuration file, connects to it at session start, and uses the tools when relevant.

An MCP tool is more powerful than a prompt because it gives the agent real data at call time. Instead of approximating what your user list looks like, the agent can call list_users and get the actual current data from your production API.

Design your tools

Good tool design follows three principles: each tool does one thing, tool names are verb-noun pairs, and input schemas are strict enough to prevent the agent from passing bad data.

Before running the generation prompt, write out your tool list with descriptions. This becomes the spec Autohand uses.

The more precise the tool description, the better the generated Zod schema and handler implementation. Autohand uses the descriptions as the tool's docstring, which the agent reads to decide when to call it.

Generate the server

Create a new directory for your MCP server and run Autohand from it.

Run the generation prompt with your tool definitions included.

Autohand scaffolds the entire project. The main server file looks like this.

Test with Autohand

Build the server and test it by running it directly first.

You should see a JSON response listing your three tools. If the server exits immediately without output, check that your INTERNAL_API_KEY is set and that the tsconfig.json output points to dist/.

Then add the server to your Autohand configuration to test in a real session.

Start a new Autohand session and verify the tools are available.

Add to your configuration

The configuration file location depends on your operating system.

For a project-level MCP server that you only want active in one codebase, add the configuration to your AGENTS.md instead of the global config.

Tip: Never commit real API keys to your AGENTS.md or config. Use a placeholder string like "ask team lead for key" in documented examples and instruct developers to use their own credentials.

Share with your team

An MCP server becomes much more valuable when the whole team uses it. Add it to a shared tools directory in your repository and document it in your project README.

Ask Autohand to generate an automated build step that compiles the MCP server as part of your main project build.

You can also ask Autohand to generate additional tools at any time by continuing the session in the MCP server directory. The server is designed to be extended.

What you learned

You designed MCP tools with verb-noun naming and strict Zod input schemas
You generated a full MCP server project using Autohand and the TypeScript SDK
You tested the server locally with a raw JSON-RPC request and then inside a live Autohand session
You added the server to your global and project-level configuration and shared it with your team

Try next autohand "Add a new MCP tool called search_tickets that calls GET /v1/tickets with query, status, and date_range parameters. Follow the same validation and error handling pattern as the existing tools."