TypeScript: one-line setup

​

Set up with your coding agent

Add Surfa analytics to this MCP server by following https://docs.surfa.dev/typescript-setup.md exactly (plain Markdown; read the whole page): install surfa-ingest, wrap the server where it's created with withSurfa(...), and add SURFA_API_KEY wherever this server's environment is configured, using the placeholder sk_live_your_key_here (if nothing in the project sets environment variables, don't create a file nothing reads: tell me where the key should go). Don't change any tool code or add decorators. When you're done, list the files you changed and tell me how to check it's working.

​

Prerequisites

• An MCP server written in TypeScript or JavaScript using @modelcontextprotocol/sdk 1.5.0 or later (McpServer or Server). Tested from 1.5.0 to 1.32.1.
• Node.js 18 or later.
• A Surfa account (sign up) and an ingest key from Settings → API Keys in the dashboard. Keys start with sk_live_.

​

Setup

npm install surfa-ingest

pnpm add surfa-ingest

yarn add surfa-ingest

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { withSurfa } from 'surfa-ingest';

const server = withSurfa(new McpServer({ name: 'my-server', version: '1.0.0' }));

// Register tools and connect exactly as before

SURFA_API_KEY=sk_live_your_key_here

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/your-server/dist/index.js"],
      "env": { "SURFA_API_KEY": "sk_live_your_key_here" }
    }
  }
}

npx @modelcontextprotocol/inspector -e SURFA_API_KEY=sk_live_your_key_here node dist/index.js

​

Configuration

const server = withSurfa(new McpServer({ name: 'my-server', version: '1.0.0' }), {
  apiKey: config.surfaKey,
  redactKeys: ['ssn', 'account_number'], // extra argument names to mask
});

​

What’s captured

• Tool name
• Arguments, with secrets masked on your server, before sending: any argument key containing password, passwd, secret, token, api_key/apikey, authorization, cookie, private_key, access_key or credential is replaced with [REDACTED], at any depth. Long strings are shortened.
• Latency in milliseconds
• Success or error, with the error message
• Response size in bytes

• Tool results. Only their size is sent.
• Your server’s environment, headers or auth tokens.
• Calls to resources and prompts (tool calls only, for now).

​

Your server is never affected

• withSurfa only observes requests and responses; it never changes them.
• Uploads run in the background, one at a time. If Surfa is slow, down or rate limiting, events are dropped; your tool calls aren’t delayed and nothing throws. At most maxQueueSize events are held in memory.
• Overhead is a few microseconds per tool call.
• Logs go to stderr only, so stdio servers keep a clean stdout.

​

Sessions and shutdown

• Tool calls are uploaded about a quarter of a second after they happen, so little is ever waiting in memory.
• When a client disconnects, the session ends and uploads straight away. This covers stdio clients closing the connection (Claude Desktop), Claude Code stopping the server with SIGINT, and containers stopped with SIGTERM. After uploading (at most one second), your process exits exactly as it would have without Surfa.
• If a server is killed before it can say goodbye (a crash, kill -9, a frozen serverless function), Surfa ends the session itself after 15 minutes without activity.

import { shutdownSurfa } from 'surfa-ingest';

process.on('SIGTERM', async () => {
  await server.close();
  await shutdownSurfa(); // add this
  process.exit(0);
});

​

Remote and serverless servers

• Long-running HTTP servers (Fly, Railway, a VPS, Docker): if you create one server per MCP session, put withSurfa inside that factory function. Each MCP session becomes one Surfa session.
• Stateless HTTP servers (a new server for every request): every tool call is recorded, but each call shows up as its own session, without the client’s name.
• Serverless functions (Vercel, AWS Lambda, Netlify): the platform can freeze your function as soon as the response is sent, before the background upload runs. Upload before returning:
  import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
  import { withSurfa, flushSurfa } from 'surfa-ingest';
  import { createServer } from './server'; // your function that builds the McpServer
  
  export async function POST(request: Request) {
    const server = withSurfa(createServer());
    const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
    await server.connect(transport);
    const response = await transport.handleRequest(request);
    await flushSurfa(); // upload before the function is frozen
    return response;
  }
  

​

Troubleshooting