Bendourthe Nexus Hub MCP Builder

MCP Builder

Build a local MCP server in Python (FastMCP) or Node / TypeScript (the official MCP SDK), then register it across all five Nexus-Hub-supported AI CLIs. The skill is opinionated about WHAT to build before HOW: many requests for "an MCP that does X" are better served by a skill (LLM-native, zero infrastructure) per the AGENTS.md MCP Registry Policy. When an MCP is the right shape, the bundled scaffolding scripts get a working server up in under 30 seconds.

When to Use This Skill

Use this skill when:

• The user wants to expose a deterministic capability the LLM cannot reliably do on its own (a database query, a filesystem operation, a service-account API call, a calculation that needs exact numerics)
• The capability is local or runs against a service the user already owns (their database, their cluster, their git repo)
• The capability returns structured data the agent will reason over (typed records, schemas, IDs)
• A skill alone is insufficient because the operation needs deterministic execution outside the LLM (e.g., "run this SQL query against my Postgres", "list pending pull requests on my repo", "publish a message to my Pub/Sub topic")
• The user wants the same capability available across multiple AI CLIs (Claude Code, Cursor, Codex, Gemini, OpenCode) - a single MCP server registers in all five

Trigger phrases: "build an MCP", "MCP server", "FastMCP", "MCP SDK", "MCP tool", "expose tools to the agent", "wrap an API as an MCP", "custom MCP", "MCP transport", "register an MCP", "model context protocol", "hello-world MCP", "spin up a tool server".

When NOT to use (apply the AGENTS.md MCP Registry Policy decision tree before building):

• The capability can be achieved by instructing the LLM directly (write code, generate text, explain a concept, summarize a doc) - ship a SKILL, not an MCP. See workflow/create-skill-or-command.
• The capability is search-as-service, embeddings-as-service, scraping-as-service, or generation-as-service - categorically rejected by policy regardless of vendor.
• The user wants to CONSUME an existing third-party MCP - that is a settings.json edit, not a build task. Cross-link catalog/mcp-configs/mcp-servers.json for the curated registry.
• The third party is the data destination but reverse-engineering is viable - prefer building a local internal MCP (per the policy) over wrapping the third party's hosted service.
• Hooks are sufficient (one-shot lifecycle event with no return value) - use a hook, not an MCP. See catalog/hooks/.
• A simple shell script invoked by the user is sufficient (not by the agent autonomously) - use a script, not an MCP.

If unsure whether the capability needs an MCP or a skill, walk the AGENTS.md decision tree explicitly with the user before scaffolding. The wrong shape costs more than the build.

When to Build vs. Skill vs. Hook (Quick Compare)

The MCP shape is the most expensive of the three. Make sure the capability actually needs deterministic execution before paying for it.

The Two Stacks

Pick by the language the underlying service is already written in. If both are equally viable, FastMCP wins on speed-to-running-server (decorator-based, fewer files); the TypeScript SDK wins on type-safety-end-to-end if the consumer is already a TS app.

Instructions

Step 0 - Decide if an MCP is the right shape

Before scaffolding, walk the AGENTS.md MCP Registry Policy decision tree with the user:

1. Is this capability local-only (their own DB, their own files, their own service)? Proceed.
2. Can the LLM do this directly via a skill? If yes, ship a skill instead.
3. Can the third party's logic be reverse-engineered locally? If yes, build a local internal MCP, not a vendor wrapper.
4. Is this a trusted-vendor wrapper for a service the user already pays for? Proceed with caution - justify per the 3-condition test.
5. Is this search / embeddings / scraping / generation as service? Drop categorically.

Only proceed past step 0 if the user confirms the capability needs deterministic execution outside the LLM AND the policy allows it.

Step 1 - Pick the stack

Ask the user (one consolidated turn):

1. Python or Node / TypeScript? (Default: match the underlying service's language; fall back to Python if neither.)
2. What is the tool's name and what does it return? (e.g., "name: query_postgres, returns: array of {row_id, value}".)
3. What transport? (stdio is the default and almost always correct for local servers; HTTP/SSE only when the server runs on a different host.)
4. Where will the server run? (Local-only is the default and simplest; remote requires more thought about auth.)

Record the answers - they shape the scaffold flags.

Step 2 - Scaffold the server

Run the bundled init script for the chosen stack:

# Python (FastMCP) - macOS / Linux
bash ~/.nexus-hub/skills/ai-development/mcp-builder/scripts/init-mcp-fastmcp.sh <server-name>

# Node / TS (MCP SDK) - macOS / Linux
bash ~/.nexus-hub/skills/ai-development/mcp-builder/scripts/init-mcp-ts.sh <server-name>

# Python (FastMCP) - Windows
& "$HOME\.nexus-hub\skills\ai-development\mcp-builder\scripts\init-mcp-fastmcp.ps1" -ServerName <server-name>

# Node / TS (MCP SDK) - Windows
& "$HOME\.nexus-hub\skills\ai-development\mcp-builder\scripts\init-mcp-ts.ps1" -ServerName <server-name>

The Python script: (a) verifies Python 3.10+; (b) creates a venv; (c) installs mcp[cli]; (d) writes <name>/server.py with one example @mcp.tool() and a __main__ block running stdio transport; (e) writes a minimal pyproject.toml; (f) prints next-step commands.

The TypeScript script: (a) verifies Node 20+; (b) runs npm init -y; (c) installs @modelcontextprotocol/sdk and zod; (d) writes <name>/src/server.ts with one example tool and stdio transport; (e) configures package.json with a dev script; (f) prints next-step commands.

Step 3 - Define your tool(s)

Edit the scaffolded server. Each tool needs:

• Name - kebab-case verb-object (query-postgres, list-pull-requests); never just a noun.
• Description - what it does, when the agent should invoke it, what it returns. The agent reads this to decide when to call - same pushy-description rule that applies to skills.
• Input schema - typed parameters with descriptions. FastMCP uses Pydantic / annotations; TS SDK uses Zod.
• Output schema - structured data, not free-form strings. The agent reasons better over {rows: [{id, name}]} than over a single string "id=1 name=foo, id=2 name=bar".
• Error handling - return an error code/message in a structured shape, not as a thrown exception that crashes the transport. The MCP protocol distinguishes tool errors from server errors.

Reference docs: deeper FastMCP API at references/fastmcp.md; deeper TS SDK API at references/ts-sdk.md.

Step 4 - Test locally

Python: mcp dev server.py opens the MCP Inspector at http://localhost:5173. The inspector lists tools, lets the user invoke each with sample input, and shows the structured output.

TypeScript: run npm run dev to start the server in stdio mode, then in a separate terminal run npx @modelcontextprotocol/inspector node ./build/server.js. Same inspector UI.

Verify before claiming success: the inspector lists all your tools; each invokes without errors on the sample input; the output schema matches the declared types.

Step 5 - Add auth (when needed)

Local stdio servers usually do not need auth - the server runs as the user, with the user's permissions. Add auth when:

• The server runs over HTTP / SSE (remote transport)
• The server holds credentials for an external service and you want to scope which agent sessions can use it
• Multi-tenancy is a requirement (multiple users hit the same server)

Both stacks support custom middleware on the transport layer. The simplest pattern: a bearer token in the Authorization header, validated against an env var (MCP_AUTH_TOKEN). For OAuth or more complex flows, consult the upstream protocol docs - the bundled scaffold does not lock you into a specific auth pattern.

Step 6 - Register the MCP across all five CLIs

Once the server runs locally, register it in each AI CLI's settings. The path varies by CLI:

The entry shape is the same across all five (the MCP protocol is the contract):

{
  "mcpServers": {
    "<server-name>": {
      "command": "python",
      "args": ["/abs/path/to/server.py"],
      "env": {
        "MCP_AUTH_TOKEN": "..."
      }
    }
  }
}

For Node / TS:

{
  "mcpServers": {
    "<server-name>": {
      "command": "node",
      "args": ["/abs/path/to/build/server.js"]
    }
  }
}

If your server is intended for the curated Nexus-Hub registry (catalog/mcp-configs/mcp-servers.json), follow the AGENTS.md MCP Registry Policy: the _comment field MUST answer the five-question audit, and the docs/policy/mcp-reverse-engineering-matrix.md MUST get a row classifying the bucket. Do NOT add to the registry without walking the policy.

Step 7 - Verify cross-CLI

Open each registered CLI in turn (or at least the user's primary plus one other) and verify:

• The CLI lists the MCP's tools in its tool inventory (Claude Code: /mcp; Cursor: status bar; Codex / Gemini / OpenCode: per their docs).
• The agent can invoke the tool with sample input.
• The agent receives the structured output and reasons over it correctly.

If a CLI doesn't list the MCP, the most common cause is a typo in the absolute path or a missing executable bit on the server script (Linux / macOS).

Common Rationalizations

Verification

Binary checklist - each item must describe an observable artifact or state.

• AGENTS.md MCP Registry Policy decision tree was walked with the user before scaffolding (recorded in chat or session-history).
• The chosen scaffolding script ran and produced a <server-name>/ directory with server.py (FastMCP) or src/server.ts (TS SDK), a runnable manifest (pyproject.toml / package.json), and the chosen transport configured.
• At least one tool is defined with a kebab-case name, an input schema, an output schema, and a non-trivial description.
• The MCP Inspector (mcp dev or mcp inspector) lists the tools, accepts sample input, and returns structured output without transport errors.
• The server's settings.json entry has been written for at least the user's primary CLI; the user has been told the same shape applies to all five (paths documented in Step 6).
• No vendor-specific search / embeddings / scraping / generation calls in the implementation (verify against the AGENTS.md hard-no list).
• If submitting to catalog/mcp-configs/mcp-servers.json, the five-question audit comment is filled and the reverse-engineering matrix has a corresponding row.
• Tool descriptions follow the pushy-description rule (list trigger phrases, list when NOT to call, include SKIP: clause for ambiguous cases).
• Cross-platform: both init-mcp-fastmcp.{sh,ps1} and init-mcp-ts.{sh,ps1} exist as siblings and produce equivalent scaffolds on their respective host shells.

"The MCP works on my machine" is not a valid verification criterion. The verification is: did the inspector confirm tools are listed, did sample input return structured output, and was Step 0 walked before the build?

Bundled Resources

The skill ships four scaffolding scripts (FastMCP and TS SDK, each with bash + PowerShell siblings) and two reference docs.

• scripts/init-mcp-fastmcp.sh - bash script for macOS / Linux. Scaffolds a FastMCP Python server with one example tool. Set executable on installer copy.
• scripts/init-mcp-fastmcp.ps1 - PowerShell sibling. Same scaffold, Windows shell.
• scripts/init-mcp-ts.sh - bash script for macOS / Linux. Scaffolds a Node / TypeScript MCP SDK server with one example tool.
• scripts/init-mcp-ts.ps1 - PowerShell sibling. Same scaffold, Windows shell.
• references/fastmcp.md - deeper FastMCP API surface: tool definitions, structured output, transports, auth, testing patterns, common pitfalls.
• references/ts-sdk.md - deeper TS SDK API surface: same topics for the Node / TypeScript stack.

The .sh and .ps1 siblings are kept parallel per the v1.1.3 four-hook precedent: every bundled .sh has a .ps1 sibling, both produce the same output, neither references the other. Cross-platform parity is enforced by the recursive-copy logic in scripts/installer.{sh,ps1} (Phase 3 of the v1.1.5 plan).

Related Skills

• [[tool-design]] -- upstream skill for designing tool / API schemas the agent consumes well; apply BEFORE scaffolding the MCP so the tool surface is well-shaped.
• [[ai-agent-development]] -- broader agent architecture context (tool use patterns, planning loops); consumes MCPs as one tool source.
• [[claude-agent-sdk]] -- Claude Agent SDK integration; consumes MCPs registered in ~/.claude/settings.json.
• [[api-design]] -- REST / gRPC / GraphQL design; relevant when wrapping an existing API as an MCP and you need the underlying API to be well-shaped first.
• [[python-expert]] -- production Python patterns for the FastMCP path.
• [[typescript-expert]] -- production TypeScript patterns for the SDK path.

Source: bendourthe/Nexus-Hub — distributed by TomeVault.