agentic-mcp-server

A production-grade Model Context Protocol server template in TypeScript, with the agentic-kit built in: one AGENTS.md every AI coding agent reads, skills that encode how to add tools, resources, and prompts, hooks that block destructive commands and force just check to pass before an agent can say "done", and a multi-model (Claude + Codex + Gemini) code-review council in CI.

It ships a small but complete example, a markdown knowledge base, exposed three ways: tools (kb.search, kb.get, kb.add, sys.time), resources (kb://index, kb://doc/{slug} with listing and completion), and prompts (summarise-doc, answer-with-sources). It runs over stdio for local hosts (Claude Code, Claude Desktop, Cursor) and over Streamable HTTP (stateless, bearer-token protected) for shared deployments. Tool handlers are SDK-free definitions; only src/server.ts and the transports touch @modelcontextprotocol/sdk, so upgrading to the v2 SDK line is a two-file change. Tests drive the server in-process through the official client, over real HTTP, and with the MCP Inspector CLI.

60-second quickstart

git clone https://github.com/kalpesh122/agentic-mcp-server my-mcp && cd my-mcp
just setup && just build
just test-inspector                # tools/list + a tools/call through the Inspector CLI

claude mcp add --scope project kb -- node dist/index.js

Requirements: Node 24 (.node-version), just. Docker only for the image.

Commands

Command	What it does
`just setup`	Install dependencies (pnpm 12 via corepack)
`just dev` / `just dev-http`	Run over stdio / Streamable HTTP with watch
`just test [pattern]`	Vitest (in-process client, HTTP transport, store, env)
`just test-inspector`	Build and drive `dist/index.js` with the Inspector CLI
`just inspect`	Open the Inspector UI against the built server
`just lint` / `just fmt`	Biome check / fix
`just typecheck`	`tsc --noEmit`
`just build`	Compile to `dist/`
`just check`	Quality gate: lint + typecheck + test + build
`just docker-build` / `just docker-up`	Image and compose (HTTP mode on 3333)
`just council`	Local multi-model code review of your branch

Capabilities

Tools

Tool	Description	Annotations
`kb.search`	Full-text search over the knowledge base; nested `filter` object (tag, sort); returns hits + `structuredContent`	read-only, idempotent
`kb.get`	Full markdown of one document by slug	read-only, idempotent
`kb.add`	Create a document; refused unless `MCP_ALLOW_WRITES=true`	write, non-destructive
`sys.time`	Current time, optional IANA zone	read-only

Resources

URI	Content
`kb://index`	JSON list of `{slug, title, tags}`
`kb://doc/{slug}`	One document as `text/markdown`; template lists all docs and completes slugs

Prompts

Prompt	Arguments	Purpose
`summarise-doc`	`slug`	Five-bullet summary of one document
`answer-with-sources`	`question`	Answer using only the knowledge base, citing slugs

Register the server

Claude Code (.mcp.json, committed in this repo):

{ "mcpServers": { "kb": { "type": "stdio", "command": "node", "args": ["dist/index.js"] } } }

HTTP mode: { "type": "http", "url": "http://localhost:3333/mcp", "headers": { "Authorization": "Bearer ${MCP_AUTH_TOKEN}" } } or claude mcp add --transport http --scope project kb http://localhost:3333/mcp --header "Authorization: Bearer $MCP_AUTH_TOKEN".

Cursor (.cursor/mcp.json): same mcpServers shape as above.

Claude Desktop (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json): same mcpServers shape; use an absolute path to dist/index.js and fully quit the app after editing.

Configuration

See .env.example. MCP_TRANSPORT (stdio | http), MCP_HTTP_PORT/MCP_HTTP_HOST, MCP_AUTH_TOKEN (required, 16+ chars, in HTTP mode), KB_DIR (markdown directory), MCP_ALLOW_WRITES, LOG_LEVEL. The --transport CLI flag overrides the env.

Folder map

src/index.ts             CLI entry (--transport), env, knowledge base, start
src/env.ts  src/log.ts   zod env · pino to stderr
src/server.ts            createServer(deps): registers tools, resources, prompts (only SDK touchpoint besides transports)
src/tools/               types.ts (defineTool, text, failure) + one file per tool + index.ts
src/resources/           kb://index, kb://doc/{slug}
src/prompts/             summarise-doc, answer-with-sources
src/kb/store.ts          KnowledgeBase (load, search, get, add)
src/transports/          stdio.ts · http.ts (express: /health, bearer-protected stateless /mcp)
test/                    helpers (in-memory client), server.test.ts, http.test.ts
data/*.md                knowledge base documents (frontmatter title/tags)
.claude/ .agents/ AGENTS.md   the agentic kit

How AI agents work in this repo

AGENTS.md (≤150 lines) is the map: commands, layout, hard rules, definition of done. CLAUDE.md imports it; Gemini, Copilot, and Cursor point at it.
Skills in .claude/skills/ (mirrored in .agents/skills/): add-tool, add-resource, add-prompt, plus the kit's brainstorm-spec, tdd, debug, code-review, council-review, verify-before-done, adr, git-hygiene.
Hooks in .claude/settings.json: block rm -rf, force pushes, reading .env; protect lockfiles; format every edited file with Biome; run just check when the agent tries to stop and block if it fails.
CI: ci.yml runs just check and the Inspector smoke, then builds the image; ai-council-review.yml has three models review every PR and post one consolidated comment.
specs/001-knowledge-base/ shows the spec → plan → tasks flow; docs/adr/ records why the stack looks like this.

Swap-outs

Domain: replace src/kb/ and the tools in src/tools/ with your own; keep defineTool and the tests' shape.
Auth: replace bearerAuth in src/transports/http.ts with OAuth 2.1 resource-server checks; keep /health public.
SDK v2 (@modelcontextprotocol/server 2.x, spec 2026-07-28): change the imports in src/server.ts and src/transports/*; tool definitions do not change.
Hosting: the image runs HTTP on 3333 behind any TLS-terminating proxy.