Deno MCP Server Template

<div align="center">

</div>

The batteries-included starting point for building production MCP servers in TypeScript.

Clone, run setup, start building. Ships with STDIO + HTTP transports, security middleware, persistent state, sandboxed execution, CI/CD workflows, and every distribution format you need -- JSR package, native binary, DXT extension, or hosted on Deno Deploy.

Why This Template?

You get a working MCP server in under 2 minutes. Not a toy -- a real server with rate limiting, CORS, session management, TLS support, and structured logging already wired up.

Deno gives you superpowers that other runtimes don't. Built-in KV database (no Postgres/Redis to set up), native cron scheduling, sandboxed code execution in microVMs, compile-to-binary, and first-class Deploy hosting. This template puts all of them to work.

Ship anywhere, any way. One codebase produces:
- a local STDIO server for Cursor, Claude Desktop, or any MCP client
- a remote HTTP server with Streamable HTTP transport
- a JSR package anyone can deno run without cloning
- a standalone native binary (no runtime needed)
- a DXT extension for one-click Claude Desktop install
- a Deno Deploy app for managed cloud hosting

AI-agent friendly codebase. Small files (<200 LOC), feature-grouped structure, explicit types. Your coding agent can navigate and extend it without context overload.

Quick Start

# Install Deno (if needed)
curl -fsSL https://deno.land/install.sh | sh
Create your project from template
gh repo create my-mcp-server --template phughesmcr/deno-mcp-template
cd my-mcp-server
One-time setup -- renames placeholders, then self-destructs
deno task setup
Start the server (STDIO + HTTP on localhost:3001)
deno task start
Or launch with MCP Inspector for interactive testing
deno task dev

Connect from any MCP client:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "deno",
      "args": ["run", "-A", "/absolute/path/to/main.ts"]
    }
  }
}

That's it. You have a running MCP server with tools, resources, prompts, and task workflows.

JSR subpath imports

When this package is published to JSR, you can import the full program (main.ts) or narrower entrypoints:

- jsr:@scope/name — same as main.ts (CLI entry).
- jsr:@scope/name/mcp — createMcpServer, mcpServerDefinition, context/subscription helpers, and related exports. The host must still open Deno KV (and any other shared services) before handling requests, same as createApp does.
- jsr:@scope/name/app — createApp for embedding the STDIO + HTTP host without copying main.ts.

See .cursor/rules/project.mdc (Architecture) for transport-scoped McpServer instances and shared context.

What's Included

Out-of-the-box infrastructure

| What | How | Where |
| --- | --- | --- |
| Dual transports | STDIO + Streamable HTTP from a single app | src/app/ |
| HTTP middleware | Rate limiting, CORS, optional bearer auth (not applied to /mcp-elicitation/* browser pages), security headers, timeouts, sessions | src/app/http/hono.ts |
| Persistent state | Deno KV -- zero-config locally, built-in on Deploy | src/kv/ |
| Session resumability | KV-backed event store for stream recovery | src/app/http/kvEventStore.ts |
| Background tasks | MCP experimental tasks: KV TaskStore + TaskMessageQueue, plus listenQueue worker for the delayed-echo demo | src/mcp/tasks/ |
| Scheduled jobs | Deno.cron for periodic maintenance | src/app/cron.ts |
| Sandboxed execution | @deno/sandbox microVMs for untrusted code | src/mcp/tools/sandbox.ts |
| MCP Apps (interactive UI) | Example tool + ui:// HTML bundle via @modelcontextprotocol/ext-apps | mcp-ui/, src/mcp/apps/, static/mcp-apps/ |
| CI/CD workflows | GitHub Actions for CI, release, deploy, JSR publish | .github/workflows/ |
| Config management | CLI flags + env vars with validation and merging | src/app/cli.ts |
| Permission preflight | Fail-fast startup checks with actionable guidance | src/app/permissions.ts |

Example MCP features (replace with your own)

Prompts: review-code, language-snippet

Resources: hello://world, greetings://{name}, counter://value (KV-backed, subscribable)

Tools: elicit-input, elicit-form-wizard (two-step form elicitation), url-elicitation-demo (URL-mode elicitation; streamable HTTP with a session only), fetch-website-info (text + optional MCP Apps UI in supporting clients), increment-counter, log-message, notify-list-changed, poem (sampling), execute-code (sandboxed)

Task workflows (experimental): delayed-echo, guided-poem (elicitation + sampling pipeline)

These cover prompts with arguments, static and dynamic resources, subscriptions, sampling, form and URL elicitation, notifications, list-changed events, KV persistence, sandboxed execution, async task patterns, and an MCP Apps UI example (fetch-website-info). Use them as reference, then swap in your domain logic.

Make It Yours

Run deno task setup first -- it rewrites package names, scopes, and metadata across the project in one pass.

Where to start editing

1. src/shared/constants/ -- server name, description, version, defaults
2. src/mcp/tools/ -- add your tools (follow existing patterns)
3. src/mcp/apps/ -- register MCP App tools/resources (@modelcontextprotocol/ext-apps/server) when you add interactive UIs
4. mcp-ui/ -- Vite bundle for MCP App HTML (run deno task build:mcp-ui; Deno installs npm deps and runs Vite — see mcp-ui/README.md)
5. src/mcp/resources/ -- add your resources
6. src/mcp/prompts/ -- add your prompts
7. src/mcp/serverDefinition.ts -- feature lists, capability flags, and derived SERVER_CAPABILITIES (re-exported from src/shared/constants/mcp.ts)
8. src/mcp/mod.ts -- server construction (registration follows the definition)
9. src/app/http/hono.ts -- adjust CORS, middleware, routes

What to remove

Delete the example files you don't need from src/mcp/tools/, src/mcp/resources/, src/mcp/prompts/, and (if you drop MCP Apps) src/mcp/apps/ plus mcp-ui/. Update the corresponding mod.ts barrel exports and any registration in src/mcp/mod.ts. Done.

HTTP security

…