Building Custom Tool Integrations

You searched for an MCP server that does what you need. Nothing. Your team has an internal deployment tool, a proprietary database, some custom API that no public MCP server covers. Now what?

You build your own. It's easier than it sounds. The protocol is well-defined, the SDK handles the heavy lifting, and you can have something working in under an hour.

When to Build vs. Use Existing

Check the MCP server registry and community repos first. Always. If something close exists, fork it and modify. That's almost always faster than starting from scratch.

Build your own when the tool is internal to your organization, when existing servers expose too much or too little of an API, or when you need custom auth flows that public servers don't support. A REST API with a couple of endpoints? Perfect candidate. Deep integration with a complex internal platform? Same approach, just more time.

Picking a Transport

Two options. Stdio: your server runs as a subprocess, communicates through stdin/stdout. HTTP: your server runs as a web service, clients connect over the network.

Start with stdio. It's simpler to build, simpler to debug, and works great when everyone runs Claude Code locally. Only reach for HTTP if you need the server on shared infrastructure or serving multiple clients simultaneously. You can always migrate later without rewriting your tool logic.

Building Your First Server

The MCP SDK at modelcontextprotocol.io/quickstart/server has everything you need. Create a Node.js project, install the SDK, define a server instance, register tools on it.

Each tool gets a name, a description, an input schema, and a handler function. The description matters more than you'd expect. Claude uses it to decide when a tool is relevant. "Deploys the current branch to staging" is vastly better than "deployment tool." Be specific about what the tool does and when it should be used, or Claude will pick the wrong tool at the wrong time.

Once Claude Code connects to your server, it reads those tool definitions and calls them as needed. The SDK handles all the protocol plumbing.

Testing Your Server

Test from the command line before wiring it into any project config:

claude mcp add --transport stdio myserver -- node server.js

Registers your server as a subprocess. Open Claude Code, ask it to use your tool, and see what happens. Stdio transport errors tend to be obvious enough to debug quickly.

Try It

Build a minimal server that exposes one tool. Pick something boring from your daily workflow. CI pipeline status check. Internal service query. Customer record lookup.

Create a directory, init a Node project, install the MCP SDK, define one tool with one parameter. Register it, test it with claude mcp add as shown above. Ask Claude Code to call the tool.

Once that works, add a second tool. Claude Code discovers it automatically, no extra configuration. MCP servers can send list_changed notifications to tell connected clients about new tools, so you can even add tools dynamically while the server is running.

Sharing With Your Team

Create a .mcp.json file at your repo root. It defines which MCP servers the project needs. Because it lives in the repo, everyone who clones gets the same tool setup. No Slack messages asking "how do I set up the deployment tool." No wiki pages that go stale three weeks later.

The format supports ${VAR} syntax for environment variable expansion (API keys, machine-specific paths). Use ${VAR:-default} for fallback values. Works in command, args, env, url, and headers fields. For project-relative paths, ${CLAUDE_PLUGIN_ROOT} resolves to wherever the config file lives, so paths work no matter where someone clones the repo.

Check .mcp.json into git. New team member clones, opens Claude Code, servers are configured.

Advanced Patterns

Once you've got a basic server working, a few patterns worth knowing:

You can use Claude Code itself as an MCP server. Run claude mcp serve and it exposes Claude's built-in tools (file viewing, editing, directory listing) to other MCP clients. Handy for chaining Claude Code into larger automation pipelines.

For enterprise environments, managed MCP configuration files (managed-mcp.json) go in system directories to control which servers are available org-wide. Allowlists, denylists, the whole thing. Matters a lot in security-sensitive setups.

You can also add your custom server to Claude Desktop via claude_desktop_config.json, giving you the same tools in the desktop app.

One Last Thing

Don't overthink this. An MCP server is a small piece of code that bridges Claude to something it can't reach. Start with stdio, a single tool, test locally, share through .mcp.json.

The servers that actually get used solve one specific problem. They don't try to wrap an entire platform. One server for deployments, another for internal metrics, a third for customer data. Small and focused wins every time.