# MCP Builder

> Use when you need to build a new MCP server — plan the tool surface, implement the server, register it in Copilot CLI, inspect the config, and test the tools end to end.

- Skill: `drvoss/mcp-builder` (Agent Skill)
- Install (CLI): `npx skillmds@latest add drvoss/mcp-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/drvoss/mcp-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: drvoss (https://skillmd.com/u/drvoss)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/drvoss/mcp-builder

---


# MCP Builder

`mcp-ecosystem` helps you install and configure existing servers. This skill is for when
you need to **build a new MCP server** for your own domain, APIs, or internal tools.
Copilot CLI makes that loop faster with native MCP management commands and workspace/user config
surfaces.

## Why This is Copilot-Exclusive

Copilot CLI has a practical MCP authoring loop built around:

- `copilot mcp add` — quick user-level server registration
- `copilot mcp list` / `copilot mcp get` — inspect what Copilot will load
- shared config paths such as workspace `.mcp.json`

That shortens the edit → inspect → load → test cycle while you build a server.

## When to Use

- You need tools for an internal API, database, or service Copilot cannot reach natively
- Existing MCP servers do not match the workflow you need
- You want a shared MCP server for a team or repository
- You need domain-specific tools with tighter validation than generic servers provide

## When NOT to Use

| Instead of mcp-builder | Use |
|------------------------|-----|
| Installing an existing MCP server | `mcp-ecosystem` |
| Using only built-in GitHub tools | built-in GitHub MCP |
| Writing a one-off local script for yourself | a normal script or CLI tool |

## Prerequisites

- Clear target users and workflows for the server
- Access to the service or API the server will wrap
- A chosen implementation stack such as TypeScript or Python
- A place to store the MCP config (workspace `.mcp.json` or user-level config)

## Workflow

### 1. Plan the tool surface

Decide whether the server should expose:

- low-level API coverage
- workflow-oriented tools
- or a mix of both

Use stable, action-oriented tool names such as:

- `db_query`
- `payments_get_invoice`
- `feature_flags_list`

### 2. Model the inputs and outputs

Every tool should define:

- explicit parameter names
- descriptions with constraints
- predictable output shape
- actionable error messages

For read-only tools, mark the intent clearly in the tool design.

### 3. Implement the server

TypeScript example:

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-service" });

server.tool(
  "my_service_lookup",
  { id: z.string().describe("Service object ID") },
  async ({ id }) => {
    const result = await lookup(id);
    return { content: [{ type: "text", text: JSON.stringify(result) }] };
  }
);
```

### 4. Register the server in MCP config

```json
// .mcp.json
{
  "servers": {
    "my-service": {
      "command": "node",
      "args": ["./tools/mcp-server.js"]
    }
  }
}
```

### 5. Centralize transport concerns

If your server talks to remote HTTP or SSE backends, keep request-scoped concerns in one
place instead of rebuilding them inside every tool:

- auth header injection
- OAuth token refresh
- trace or correlation IDs
- tenant or user context propagation

Whether your stack calls these **interceptors**, **middleware**, or **request wrappers**,
the rule is the same: tool handlers should focus on business logic, while transport policy
stays in a reusable layer.

### 5a. Design token-dense tool responses

Default every tool's response shape to be token-dense, not just correct. An LLM caller pays
context-window cost for every token a tool returns, so a verbose or redundantly-nested response
shape is a recurring tax on every future call, not a one-time cost.

- Prefer compact, flat structures over deeply nested JSON with repeated keys
- Strip fields the caller cannot act on (internal IDs, boilerplate metadata) unless a tool
  explicitly needs them
- Consider a compact serialization format for tools that return large structured results
  ([TOON](https://github.com/DeusData/codebase-memory-mcp) is one example reporting roughly 90%
  token reduction versus naive JSON on graph/trace-shaped output — treat vendor-reported
  reduction numbers as a claim to verify against your own payloads, not a guarantee)
- Measure actual token cost on a representative response before and after a format change

### 5b. Use routing hints to defer low-probability tools

If the server exposes many tools but most calls only need a handful, do not force every tool's
full schema into the initial discovery response. Expose a smaller set of high-probability tools
up front, and attach routing hints (a short description of what else is available and when to ask
for it) so the caller can request the rest only when needed.

This avoids a full discovery round-trip for tools that are rarely used, which matters most for
servers with a large or long-tail tool surface. Promote a deferred tool to fully visible only when
its routing hint condition is actually triggered by the caller's request.

### 6. Inspect, load, and test

Use Copilot CLI's built-in management flow:

```text
1. Register or edit the server config
2. Inspect it with `copilot mcp list` and `copilot mcp get <name>`
3. Start or refresh a Copilot session so the server is loaded
4. Call the new tool with a real test input
```

### 7. Add lightweight evaluations

Before sharing the server, prepare realistic prompts that prove:

- the tool is discoverable
- the parameters are understandable
- the output is useful to an LLM-driven workflow

## Quality Checklist

- [ ] Tool names are stable and action-oriented
- [ ] All parameters have descriptions
- [ ] Output shape is predictable
- [ ] Errors tell the caller what to fix next
- [ ] Auth, header, or request-context propagation is centralized instead of duplicated per tool
- [ ] Tool responses are token-dense — no redundant nesting or fields the caller can't act on
- [ ] Low-probability tools use routing hints instead of forcing full upfront discovery
- [ ] The config is visible in `copilot mcp list`
- [ ] At least one end-to-end tool invocation succeeds after the server is loaded

## Common Rationalizations

| Rationalization | Reality |
|----------------|---------|
| "I'll just expose every endpoint" | Too many low-value tools make the server harder to use well. |
| "The schema is obvious" | LLMs rely on explicit parameter descriptions and output shape. |
| "I can skip inspection and test it live" | Bad config slows iteration and creates avoidable confusion. |
| "A generic wrapper is enough" | Workflow-specific tools often serve agents better than raw API mirrors. |
| "I'll copy the auth headers in each tool" | Request policy belongs in one interceptor or middleware layer so it stays correct everywhere. |

## Red Flags

- Tool names describe implementation details instead of user tasks
- Inputs are under-specified or ambiguous
- The server requires hidden setup not captured in config or docs
- Every tool reconstructs auth or trace headers manually
- You have not tested the tool from Copilot after loading the server

## Verification

- [ ] The server solves a concrete workflow gap that built-in tools do not cover
- [ ] MCP config is visible in `copilot mcp list`
- [ ] `copilot mcp get <name>` shows the expected command, env, or URL
- [ ] At least one real prompt can discover and use the tool correctly

## Tips

- Start with 2-5 high-value tools, not exhaustive API coverage
- Prefer project-level `.mcp.json` when a team should share the server
- Pair this with `source-driven-development` when wrapping a third-party SDK or API

## See Also

- [`mcp-ecosystem`](../mcp-ecosystem/SKILL.md) — install and manage existing MCP servers
- [`source-driven-development`](../../development/source-driven-development/SKILL.md) — verify SDK usage against official docs
- [`skill-creator`](../../development/skill-creator/SKILL.md) — create supporting skills for your MCP workflow