Deno Mcp Template

Deno MCP Server Template

[](https://jsr.io/@phughesmcr/deno-mcp-template) [](https://jsr.io/@phughesmcr/deno-mcp-template)

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 ( \ --app \ --source local \ --runtime-mode dynamic \ --entrypoint main.ts \ --build-timeout 5 \ --build-memory-limit 1024 \ --region us

Deploy

deno deploy --prod

Set `DENO_DEPLOY_TOKEN`, `DENO_DEPLOY_ORG`, and `DENO_DEPLOY_APP` in GitHub Actions secrets for automatic deploys. Remove `.github/workflows/deploy.yml` if not using Deploy.

## Production Checklist

- [ ] Run `deno task setup` and verify all placeholder names are replaced
- [ ] Remove or replace demo tools/resources/prompts you won't ship
- [ ] Update `static/.well-known/openapi.yaml` and `static/dxt-manifest.json`
- [ ] Configure `MCP_ALLOWED_ORIGINS` and `MCP_ALLOWED_HOSTS` for your environments
- [ ] Replace `src/app/http/kvEventStore.ts` with a production-grade event store (the included one is a demo)
- [ ] Switch from `deno run -A` to [explicit permissions](https://docs.deno.com/runtime/fundamentals/security/) for production
- [ ] Review `--allow-net` scope for any outbound tool calls
- [ ] Set environment variables in CI and hosting provider
- [ ] Run `deno task ci` (format, lint, type-check, test)

## Configuration

| Variable | Flag | Default | Description |
| --- | --- | --- | --- |
| `MCP_NO_HTTP` | `--no-http` | `false` | Disable HTTP server |
| `MCP_NO_STDIO` | `--no-stdio` | `false` | Disable STDIO transport |
| `MCP_HOSTNAME` | `-n` | `localhost` | HTTP listen hostname |
| `MCP_PORT` | `-p` | `3001` | HTTP listen port |
| `MCP_PUBLIC_BASE_URL` | `--public-base-url` | | Public `http(s)://` origin for browser links (URL elicitation); no trailing slash |
| `MCP_TLS_CERT` | `--tls-cert` | | PEM certificate path (requires `--tls-key`) |
| `MCP_TLS_KEY` | `--tls-key` | | PEM private key path (requires `--tls-cert`) |
| `MCP_HEADERS` | `-H` | | Response headers (collection) |
| `MCP_JSON_RESPONSE` | `--json-response` | `false` | JSON-only responses (disable SSE) |
| `MCP_DNS_REBINDING` | `--dnsRebinding` | `false` | Enable transport-level Origin/Host checks (loopback binds already get Host validation) |
| `MCP_ALLOWED_ORIGINS` | `--origin` | | Allowed CORS origins (collection) |
| `MCP_ALLOWED_HOSTS` | `--host` | | Allowed hostnames (collection) |
| `MCP_KV_PATH` | `--kv-path` | | Custom Deno KV database path |
| `MCP_MAX_TASK_TTL_MS` | `--max-task-ttl-ms` | `86400000` (24h) | Max client-requested TTL (ms) for experimental MCP tasks; clamped in `KvTaskStore` (min 60s, max 1y — see `src/shared/validation/config.ts`) |
| `DENO_DEPLOY_TOKEN` | | | Deploy token (required by `execute-code` sandbox tool) |

CLI flags override env vars. Collection values (`-H`, `--origin`, `--host`) are merged from both sources.

### Collection config examples

Collection-style values can be set as comma-separated strings in `.env`:

```env
MCP_HEADERS=x-api-key:demo,cache-control:no-store
MCP_ALLOWED_ORIGINS=http://localhost:6274,https://app.example.com
MCP_ALLOWED_HOSTS=localhost,127.0.0.1,app.example.com

Or repeated CLI flags:

deno task start -- \
  -H "x-api-key:demo" \
  -H "cache-control:no-store" \
  --origin "http://localhost:6274" \
  --origin "https://app.example.com" \
  --host "localhost" \
  --host "app.example.com"

Use --origin for full origins (e.g. https://example.com) and --host for hostnames or IPs (e.g. example.com, 127.0.0.1).

Development

| Command | What it does | | --- | --- | | deno task start | Start server | | deno task dev | Start with MCP Inspector + watch mode | | deno task build:mcp-ui | Build MCP App HTML into static/mcp-apps/ (Deno + mcp-ui/deno.lock; no Node.js) | | deno task ci | Runs build:mcp-ui, then format, lint, type-check, and test | | deno task test:integration | Run integration tests | | deno task test:coverage | Tests with coverage report | | deno task bench | Run benchmarks |

deno task ci runs build:mcp-ui first, which uses Deno-only install + Vite under mcp-ui/ (see mcp-ui/README.md). CI only needs Deno for that step.

Runtime permissions

The app validates required permissions at startup and fails fast with actionable guidance. For production, prefer explicit permissions over -A:

# HTTP + STDIO (local defaults)
deno run --env-file=.env \
  --allow-env --allow-read --allow-write --allow-sys \
  --allow-net=localhost:3001 \
  main.ts

# STDIO only (no HTTP listener)
deno run --env-file=.env \
  --allow-env --allow-read --allow-write --allow-sys \
  main.ts --no-http

If you keep networked tools (such as fetch-website-info), include their destinations in --allow-net.

Lockfile and reproducibility

This template tracks deno.lock for deterministic dependency resolution.

• Refresh lock data: deno install --entrypoint main.ts --frozen=false
• Verify locked resolution (CI): deno install --frozen --entrypoint main.ts
• Commit deno.lock with dependency changes.

Project Structure

main.ts                     # Entry point
src/
  app/                      # Runtime shell: transports, HTTP, KV, cron, signals
  mcp/                      # MCP server: tools, resources, prompts, tasks, apps
  shared/                   # Constants, types, validation, utilities
mcp-ui/                     # Vite + ext-apps front-end for MCP App HTML bundles
static/                     # Static files, OpenAPI spec, DXT manifest, mcp-apps/*.html
scripts/                    # Setup, build, and packaging helpers
test/                       # Integration tests and benchmarks
.github/workflows/          # CI, release, deploy, publish

For the annotated source tree, transport internals, and development caveats, see [.cursor/rules/project.mdc](.cursor/rules/project.mdc).

Extras

Included quality-of-life files:

• .cursor/rules/ -- Cursor agent rules for this project
• .cursor/skills/ -- Agent skills for implementing tools, resources, and prompts (see below)
• .cursorignore -- tells Cursor to exclude files in addition to .gitignore
• .vscode/ -- recommended extensions, Deno as default formatter
• .github/ -- CI/CD workflows, sponsors config, issue templates
• CLAUDE.md -- optional Claude Code project context
• CODE_OF_CONDUCT.md, CONTRIBUTING.md, etc. -- community management files for GitHub

Skills

The .cursor/skills/ directory contains agent skills that guide Cursor through implementing MCP features in this template. Each skill provides file templates, registration steps, type signatures, and working examples.

| Skill | What it covers | | --- | --- | | [implementing-mcp-tools](.cursor/skills/implementing-mcp-tools/SKILL.md) | Standard tools, sampling, form and URL elicitation, resource-backed tools, notifications | | [implementing-mcp-resources](.cursor/skills/implementing-mcp-resources/SKILL.md) | Static resources, KV-backed resources, resource templates, subscriptions | | [implementing-mcp-prompts](.cursor/skills/implementing-mcp-prompts/SKILL.md) | Prompts with static arguments or dynamic completions |

These skills are picked up automatically by Cursor when relevant. Ask the agent to "add a new tool" or "create a resource" and it will follow the project's patterns.

References

• MCP Specification
• MCP Apps / @modelcontextprotocol/ext-apps (interactive tool UIs)
• MCP Concepts
• Deno Docs
• Deno Deploy
• Deno Sandbox
• Hono

Acknowledgements

If you use this template, please consider contributing fixes and features, starring the repo, and sponsoring.

This is not an official Deno project.

License

MIT -- this is a template, not a library. You're expected to modify it before shipping to production.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: phughesmcr
• Source: phughesmcr/deno-mcp-template
• License: MIT
• Homepage: https://jsr.io/@phughesmcr/deno-mcp-template

Install and usage instructions live in the source repository linked above.