mcp-tool-server

One MCP tool, four front doors, one implementation: a core domain layer, a CLI adapter for humans and CI, a transport-agnostic server.ts, and one file per transport binding — stdio for coding agents, Streamable HTTP for hosted callers, authenticated with @cogs/auth service tokens.

Genericized from cates-works/packages/mcp-content-server, whose server.ts already isolated its StdioServerTransport binding to a single line. This skill proves that property was real rather than incidental by adding a second binding over the same server — not a second server.

What it covers

• The four-layer split. core/ owns the operations and is the only place domain behaviour lives; cli/ and mcp/server.ts are wrappers over the same getTool(name) dispatch, so they cannot disagree; index-stdio.ts and index-http.ts are the only files that name a transport.
• Thin tools, verbatim errors. A tool builds a request, sends it, relays the result. The API keeps its validation and authorization rules; a non-2xx surfaces as an MCP tool error carrying the upstream's own status/error/code, never a protocol failure.
• Credential handling. Env-over---config resolution, a startup token-prefix shape check so a pasted JWT fails fast and locally, and exactly one sanctioned rendering of a token anywhere (redactToken — prefix + length).
• Verify-before-handler on HTTP. Route → manager.verify() → scope check, and only then is an McpServer constructed. It is an ordering property, so the test asserts it with a call-counting source rather than status codes.
• Service-token auth. @cogs/auth's createServiceTokenManager: prefixed, hashed at rest, TTL-capped, per-resource × verb scopes closed at the type level, and a live creator re-check on every request so deactivating a human instantly kills every token they minted.
• Sink-level redaction. The logger is wrapped once with a pattern derived from manager.redactionPattern, so a log line added later is covered by default — while the token's id and scope list survive, because those are what make a request attributable and revocable.
• A distributable skill.md. Teaches an agent to prefer the MCP tool and fall back to the CLI, with the fallback conditions spelled out concretely.

Explicitly not built

Documented as deferred extension points, not silently absent:

• OAuth / Clerk remote-connector auth — no shipped reference. The HTTP binding authenticates service tokens only.
• A Zitadel auth backend — no shipped reference. Zero consumers today.

Both would attach at the same seam (references/mcp/http-auth.ts). Building either is new work, not the closing of a gap. See SKILL.md.

Use it

Read SKILL.md for the 9 invariants, the four-check verification loop, and the red flags. The reference in references/ is runnable, not illustrative:

cd skills/mcp-tool-server/references
npm install
npm run typecheck                          # tsc --noEmit, clean
npm test                                   # 26 tests
npm run cli -- list-items --tag starter    # works with zero config

Then take core/, cli/, mcp/, tests/, rename the example-tool / exsvc_ / EXAMPLE_TOOL_* placeholders, and rewrite the two files that are actually yours: core/operations.ts and createHttpItemSource in mcp/client.ts. references/README.md has the copy-in checklist and the @cogs/auth dependency notes.

Install globally

Symlink into your global skills the same way as the other next-starters skills:

skills add [email protected]:catesandrew/next-starters.git --skill skills/mcp-tool-server -g

Companion

docs/HARVEST-MCP-TOOLING.md is the survey this skill came out of — what was already shared, what had been copy-pasted three times and drifted, and what stays per-repo by design. docs/MCP-TOOLING-RUNBOOK.md is the thin index across both. The token mint/verify/revoke contract itself lives in @cogs/auth's ./service-tokens entrypoint, published in 0.5.0 and imported here as a real dependency.