> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpfy.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript

> Install and configure mcpfy-pulse for Node.js MCP servers built on mcpfy-sdk or the official @modelcontextprotocol/sdk

## Prerequisites

* Node.js `^20.19.0` or `>=22.12.0`
* An MCPFY API key - see [Get your API key](/docs/pulse-sdk/overview#get-your-api-key) if you don't have one yet

There are three ways to use `mcpfy-pulse`. None of them edit your files for you - pick the one that matches your situation.

<Tabs>
  <Tab title="Using mcpfy-sdk">
    No install step - `mcpfy-pulse` ships bundled with `mcpfy-sdk`. Just set one environment variable and restart your server however you normally do:

    ```bash theme={null}
    MCPFY_API_KEY=mk_live_xxx node dist/server.js
    ```

    `mcpfy-sdk` checks for `MCPFY_API_KEY` internally and wraps its own transport automatically. Unset the variable and nothing changes - no code path is even touched.
  </Tab>

  <Tab title="Your own server (raw SDK)">
    For anyone who wrote their own server on the raw `@modelcontextprotocol/sdk` (or anything else that exposes a `Transport`) and has the source in front of them.

    <Steps>
      <Step title="Install the package">
        ```bash theme={null}
        npm install mcpfy-pulse
        ```
      </Step>

      <Step title="Set your API key">
        In your `.env` file:

        ```bash theme={null}
        MCPFY_API_KEY=mk_live_xxx
        ```
      </Step>

      <Step title="Wrap your transport">
        Right before you connect it. This works for any transport - stdio, HTTP, SSE - not just the stdio example below:

        ```ts theme={null}
        import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
        import { withMcpfyTelemetry } from "mcpfy-pulse";

        const transport = new StdioServerTransport();
        await server.connect(
          withMcpfyTelemetry(transport, { apiKey: process.env.MCPFY_API_KEY })
        );
        ```

        `withMcpfyTelemetry` wraps the `Transport`'s `onmessage`/`send` seam - the two points every JSON-RPC message passes through regardless of which SDK built the server. If `apiKey` is unset, it returns the original transport unchanged, so it's safe to leave this in place across environments.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Someone else's server (no source)">
    No install step - `npx` fetches `mcpfy-proxy` automatically the first time it runs. Edit your MCP client's config (`claude_desktop_config.json`, Cursor's `mcp.json`, etc.) to route the command through the proxy:

    ```jsonc theme={null}
    // before:
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }

    // after:
    "github": {
      "command": "npx",
      "args": ["-y", "mcpfy-proxy", "--", "npx", "-y", "@modelcontextprotocol/server-github"],
      "env": { "MCPFY_API_KEY": "mk_live_xxx" }
    }
    ```

    `mcpfy-proxy` becomes the process your client spawns. It spawns the real command as its own child, sits in that child's stdin/stdout, and forwards every byte unchanged while classifying JSON-RPC messages on the side. Works for any language - Python, Go, Rust, anything - since it only ever reads newline-delimited JSON off a pipe.
  </Tab>
</Tabs>

## Advanced options

`withMcpfyTelemetry` and the `mcpfy-sdk` integration both accept the same options object, and every field falls back to an environment variable if omitted:

| Option            | Env var                    | Default                                    |
| ----------------- | -------------------------- | ------------------------------------------ |
| `apiKey`          | `MCPFY_API_KEY`            | *(required to send data)*                  |
| `endpoint`        | `MCPFY_TELEMETRY_ENDPOINT` | `https://api.mcpfy.ai/v1/telemetry/ingest` |
| `flushIntervalMs` | -                          | `5000`                                     |
| `maxBatchSize`    | -                          | `500`                                      |

## What's next

Once your server sends its first event, head to the dashboard to see it.

<Card title="View telemetry in the dashboard" icon="chart-line" href="/docs/pulse-sdk/dashboard">
  See tool-level usage, health scores, and quality signals once data starts flowing.
</Card>