# @tanstack/ai-secure-mcp
A security envelope around [`createMCPServer`](https://www.npmjs.com/package/@tanstack/ai-mcp)
for a self-hoster who wants to expose a TanStack AI MCP server to the internet.
It wraps your server with:
- **Hashed-token auth** — bearer tokens stored as SHA-256 hashes, constant-time compare.
- **Scopes and a target allowlist** — a token holds scopes; a scope can be narrowed to named resources.
- **Deny-by-default egress** — one allowlisted `egress` capability, no generic `fetch`.
- **Rate limits** — a per-client sliding window.
- **A redacted audit log** — append-only JSONL, args redacted to id-like fields, no secrets.
- **A tripwire notifier** — push a signal to your phone when someone pokes at the server.
- **Two-phase approval** — a tool can return a proposal; a separate confirm runs the action.
- **Go-live preflight** — refuses a public funnel while a secure default is off.
## Installation
```bash
pnpm add @tanstack/ai-secure-mcp
```
## Quick start
```typescript
import {
createSecureMcpServer,
hashToken,
ntfyNotifier,
} from '@tanstack/ai-secure-mcp'
import type { AnyServerTool } from '@tanstack/ai'
declare const hueTools: Array
const server = createSecureMcpServer({
name: 'home',
version: '1.0.0',
tools: hueTools,
clients: [
{
id: 'alice',
// Store the hash, never the raw token.
tokenHash: hashToken('the-raw-token-alice-holds'),
scopes: ['read', 'control'],
},
],
egress: ['https://api.hue.local'], // deny-by-default allowlist
policy: {
scopes: { setLights: 'control' }, // setLights needs the control scope
approve: ['buyMovie'], // buyMovie needs two-phase approval
},
audit: { path: './audit.jsonl', retentionDays: 90 },
notify: ntfyNotifier({ topic: 'my-home-mcp' }),
funnel: { port: 8787 },
})
// Serve it from your HTTP handler.
export default server.fetch
```
`server.preflight` holds the secure-default problems. `server.tailscale` holds
the command to expose the server when you pass `funnel`.
## Reaching the network from a tool
A tool receives the `egress` capability on `ctx.context`. It is the only way to
the network, and it refuses any origin not on the allowlist.
```typescript
import { toolDefinition } from '@tanstack/ai'
import { z } from 'zod'
import type { SecureRequestContext } from '@tanstack/ai-secure-mcp'
const getLights = toolDefinition({
name: 'getLights',
description: 'List the lights on the Hue bridge',
inputSchema: z.object({}),
}).server(async (_args, ctx) => {
const res = await ctx.context.egress('https://api.hue.local/lights')
return { status: res.status }
})
```
## Two-phase approval
A tool in `policy.approve` does not act on the first call. It returns an
envelope:
```json
{ "status": "approval_required", "proposalId": "…", "summary": "Run buyMovie" }
```
A separate, authenticated call to the `approve_proposal` tool with that
`proposalId` runs the action. Proposals are in memory, single-use, and expire,
so a crash cannot leave a ghost approval.
## Secure defaults
| Concern | Default | Footgun it prevents |
| --- | --- | --- |
| Egress | deny-by-default allowlist | a tool exfiltrating data |
| Generic HTTP | not injectable | SSRF through a "helpful" tool |
| Tokens | hash-only, constant-time | replay from a leaked store |
| Secrets | never in the audit log or a notification | prompt/response exfiltration |
| Approval state | in memory, fail-closed on restart | a ghost approval after a crash |
| Exposure | tailnet-only unless you opt into a public funnel | accidental internet |
The preflight refuses a public funnel while a token is unhashed, egress is open,
or the audit log or notifier is off. The funnel URL is not a secret: auth stands
on its own.
## License
MIT