# mcp-ts-core

A TypeScript framework for building MCP servers, with foundations for tools, access control, storage, logging, and transports. Use it to connect an API or workflow to an AI agent.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 152
- Author: cyanheads
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cyanheads/mcp-ts-core
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-ts-core

## What it does

mcp-ts-core provides the server foundation while your project supplies its domain logic. Define typed tools, resources, prompts, and MCP Apps; the framework also covers access control, tenant-scoped storage, and logging. Servers can use stdio or HTTP on Bun and Node.js, with a separate entry point for Cloudflare Workers.

Start a project with `bunx @cyanheads/mcp-ts-core init my-mcp-server`. The scaffold contains source files, build and test configuration, agent instruction files, and Agent Skills for tool design, testing, security review, and releases. To add the server in Claude Code, run `claude mcp add mcp-ts-core -- npx -y @cyanheads/mcp-ts-core`. Bun projects require Bun; the Node.js option requires Node.js 24 or newer. DuckDB, Supabase, and the OpenTelemetry SDK are optional peer dependencies, so install them when using those integrations.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `MCP_LOG_LEVEL`, `MCP_TRANSPORT_TYPE`, `MCP_HTTP_HOST`, `MCP_HTTP_PORT`, `MCP_HTTP_ENDPOINT_PATH`, `MCP_AUTH_MODE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env MCP_LOG_LEVEL=<MCP_LOG_LEVEL> --env MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> --env MCP_HTTP_HOST=<MCP_HTTP_HOST> --env MCP_HTTP_PORT=<MCP_HTTP_PORT> --env MCP_HTTP_ENDPOINT_PATH=<MCP_HTTP_ENDPOINT_PATH> --transport stdio mcp-ts-core -- npx -y @cyanheads/mcp-ts-core
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Codex

**Platform CLI**
```bash
codex mcp add mcp-ts-core --env MCP_LOG_LEVEL=<MCP_LOG_LEVEL> --env MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> --env MCP_HTTP_HOST=<MCP_HTTP_HOST> --env MCP_HTTP_PORT=<MCP_HTTP_PORT> --env MCP_HTTP_ENDPOINT_PATH=<MCP_HTTP_ENDPOINT_PATH> -- npx -y @cyanheads/mcp-ts-core
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp-ts-core": {
            "command": "npx",
            "args": [
                "-y",
                "@cyanheads/mcp-ts-core"
            ],
            "env": {
                "MCP_LOG_LEVEL": "<MCP_LOG_LEVEL>",
                "MCP_TRANSPORT_TYPE": "<MCP_TRANSPORT_TYPE>",
                "MCP_HTTP_HOST": "<MCP_HTTP_HOST>",
                "MCP_HTTP_PORT": "<MCP_HTTP_PORT>",
                "MCP_HTTP_ENDPOINT_PATH": "<MCP_HTTP_ENDPOINT_PATH>"
            }
        }
    }
}
```
Replace <…> with your own values. 1 more environment variable is in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp-ts-core": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@cyanheads/mcp-ts-core"
            ],
            "env": {
                "MCP_LOG_LEVEL": "<MCP_LOG_LEVEL>",
                "MCP_TRANSPORT_TYPE": "<MCP_TRANSPORT_TYPE>",
                "MCP_HTTP_HOST": "<MCP_HTTP_HOST>",
                "MCP_HTTP_PORT": "<MCP_HTTP_PORT>",
                "MCP_HTTP_ENDPOINT_PATH": "<MCP_HTTP_ENDPOINT_PATH>"
            }
        }
    }
}
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e MCP_LOG_LEVEL=<MCP_LOG_LEVEL> -e MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> -e MCP_HTTP_HOST=<MCP_HTTP_HOST> -e MCP_HTTP_PORT=<MCP_HTTP_PORT> -e MCP_HTTP_ENDPOINT_PATH=<MCP_HTTP_ENDPOINT_PATH> mcp-ts-core npx -y @cyanheads/mcp-ts-core
```
Replace <…> with your own values. 1 more environment variable is in the server README

## When to use it
- scaffold an MCP server around an API
- define typed inputs and outputs for a tool
- expose resources and prompts to an agent
- provide recovery guidance for declared errors
- test tool definitions and catch contract issues

## Example prompts
- Create an MCP server for our inventory API with a product search tool.
- Add a stock-checking tool to this MCP server and define its input and output schemas.
- Review the tool definitions for errors and set up server tests.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [Front-End Checklist](https://affpapa.org/en/nevibecode/mcp/front-end-checklist.md) — MCP server · ★ 74559
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md