Extend it · TypeScript MCP server starter
Give your agents tools without opening a hole in your server.
Toolport is a TypeScript starter for a production Model Context Protocol server — the thing that lets Claude, Cursor, or any MCP client call your tools. Typed and validated tools, auth, rate limiting, error contracts, and both transports, with three worked tools that show the safe way to do the dangerous things.
Typed tools in one helper
defineTool() takes a Zod schema and a handler and gives you validation, a size cap, rate limiting and a consistent error contract for free. Register a new tool in a few lines.
Both transports, out of the box
Local stdio for desktop clients and a stateless Streamable HTTP transport with bearer auth and a /health check for remote deploys — same tools, either way.
Three tools that show the safe pattern
http-fetch (allowlisted, no SSRF proxy), file-read (sandboxed, path-escape guarded), and db-query (read-only Supabase REST, no raw SQL) — the right way to do the things that usually get servers owned.
Real smoke tests
The suite spins up the server in-memory with a real MCP client and calls the tools — so "it works" is proven, not asserted. verify.sh runs typecheck, lint, build and tests.
Straight from the source
A real tool from the kit — allowlist + GET-only + truncation, so it can't become an SSRF proxy.
export const httpFetchTool = defineTool({
name: "http_fetch",
title: "HTTP fetch (allowlisted)",
input: z.object({ url: z.string().url() }),
async handler({ url }, { config, log }) {
const parsed = new URL(url);
if (!config.fetchAllowlist.includes(parsed.hostname))
throw new Error(`Host "${parsed.hostname}" is not on the allowlist.`);
const res = await fetch(parsed, { method: "GET",
signal: AbortSignal.timeout(10_000) });
return (await res.text()).slice(0, MAX_BODY);
},
});What's in the zip
A real slice of the shipped tree — small enough that you and your agent can read every file.
- src/lib/tool.tsdefineTool() + registerTools() — the whole ergonomic core
- src/tools/http-fetch.tsallowlisted web fetch (SSRF-safe)
- src/tools/file-read.tssandboxed file read, path-escape guarded
- src/tools/db-query.tsread-only Supabase REST, no raw SQL
- src/transports/stdio.tslocal transport for desktop clients
- src/transports/http.tsstateless Streamable HTTP + bearer auth + /health
- src/lib/rate-limit.tsfixed-window limiter per session
- src/config.tsZod-validated env — fails fast on misconfig
- test/smoke.test.tsin-memory MCP client exercises every tool
Why start here instead of the SDK docs
The MCP SDK gives you a server object. Everything between that and a server you'd actually expose — input validation, auth, rate limits, an error contract, a safe way to fetch/read/query, a deploy story, and tests that prove it — is on you. Toolport is that layer, built once and hardened, with three tools that demonstrate the safe pattern for the operations that most often get a server compromised.
In the box
- TypeScript + the official @modelcontextprotocol/sdk
- defineTool() — Zod-validated, rate-limited, size-capped tools
- stdio + stateless Streamable HTTP transports, bearer auth, /health
- Three worked tools: HTTP fetch, file read, DB query — all hardened
- In-memory smoke tests + verify.sh gate
- Client recipes for Claude Desktop, Cursor and raw HTTP
Questions
- What can clients actually do with it?
- Any MCP client — Claude Desktop, Cursor, or your own — can discover and call the typed tools you define. The kit includes ready-to-paste config recipes for the common clients plus raw HTTP.
- Do I have to use Supabase?
- No. The db-query tool is an opt-in example that only registers when you set the Supabase env vars. Delete it or swap in your own data source — the http-fetch and file-read tools stand alone.
- Is it really production-ready or just a demo?
- It compiles clean, lints clean, and its smoke tests spin up the server in-memory with a real MCP client and call every tool. Auth, rate limiting, size caps and a consistent error contract are built in. You add your tools and deploy.
- Which licence do I get?
- Unlimited personal and client projects. You can't resell Toolport itself as a competing starter.
Own it outright. Extend it with your agent.
New to the fleet? Start free with AgentShip Lite →