Quickstart

Create a vendor, install the SDK, track your MCP server, and verify that SDK activity appears in the Within dashboard.

Prerequisites

• A TypeScript/JavaScript MCP server using @modelcontextprotocol/sdk (Node.js 20 or later), or a Python MCP server using mcp 1.2+ / 2.x or community FastMCP v2 or v3 (Python 3.11 or later).

1. Create your Within account and vendor

1. Create a Within dashboard account.
2. Enter the verification code sent to your work email, then sign in.
3. Create a vendor. Its permanent vendor slug scopes API keys and historical SDK activity.
4. Open Settings → SDK Setup, generate an SDK API key, and save it when it is revealed. The plaintext key is shown only once.

Keep the SDK API key in server-side environment or secret storage. Do not expose it in browser code or commit it to source control.

2. Install and configure the SDK

TypeScript

npm install within-sdk @modelcontextprotocol/sdk

Python

pip install within-sdk

Add the vendor slug and SDK API key to the environment of the process that runs your MCP server:

WITHIN_VENDOR_SLUG=acme
WITHIN_SDK_API_KEY=within_sk_xxx

3. Track your MCP server

Create your MCP server normally and call track() after registering tools.

TypeScript

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { track } from 'within-sdk';

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

server.tool('search_companies', SearchCompaniesSchema, async (args) => {
  return searchCompanies(args);
});

track(server, process.env.WITHIN_VENDOR_SLUG!, {
  apiKey: process.env.WITHIN_SDK_API_KEY!,
});

export { server };

Python

import os

from mcp.server import MCPServer  # mcp 1.x: from mcp.server.fastmcp import FastMCP
from within_sdk import track, WithinOptions

server = MCPServer("acme")


@server.tool()
def search_companies(query: str) -> str:
    return do_search(query)


# api_key is read from the WITHIN_SDK_API_KEY environment variable
track(server, os.environ["WITHIN_VENDOR_SLUG"], WithinOptions())

The SDK observes supported MCP traffic in the background. Tool outputs and errors are unchanged.

4. Add identity when available

If your MCP runtime can resolve a stable vendor-local user, account, workspace, or customer ID, add identify() to the same track() call:

TypeScript

track(server, 'acme', {
  apiKey: process.env.WITHIN_SDK_API_KEY!,
  async identify(_request, extra) {
    const user = await lookupUserFromSession(extra?.sessionId);
    if (!user) return null;
    return {
      userId: user.internalCustomerId,
      userData: {
        plan: user.plan,
      },
    };
  },
});

Python

from within_sdk import UserIdentity


def identify(request, context):
    user = lookup_user_from_request(context)  # e.g. claims off context.request
    if not user:
        return None
    return UserIdentity(
        user_id=user.internal_customer_id,
        user_data={"plan": user.plan},
    )


track(server, "acme", WithinOptions(identify=identify))

The SDK hashes the user ID locally before SDK activity leaves your process. Use an opaque ID rather than email, name, or org-domain values.

5. Verify SDK activity

Restart the MCP server and call one meaningful tool in your local or staging environment. Open Overview in the Within dashboard and select the vendor. The first-run checklist updates after SDK activity arrives.

If no activity appears, make sure the running process uses the tracked server instance and has both WITHIN_VENDOR_SLUG and WITHIN_SDK_API_KEY.

6. Report a confirmed conversion

When the same user becomes a subscriber, report the same opaque user ID from trusted server-side checkout, webhook, or account-upgrade code.

TypeScript

import { reportConversion } from 'within-sdk';

await reportConversion({
  vendorSlug: process.env.WITHIN_VENDOR_SLUG!,
  apiKey: process.env.WITHIN_SDK_API_KEY!,
}, {
  userId: user.internalCustomerId,
  convertedAt: new Date(),
  plan: {
    id: 'pro',
    name: 'Pro',
    interval: 'month',
  },
});

Python

import os
from datetime import datetime, timezone

from within_sdk import report_conversion

report_conversion(
    os.environ["WITHIN_VENDOR_SLUG"],
    os.environ["WITHIN_SDK_API_KEY"],
    user.internal_customer_id,
    converted_at=datetime.now(timezone.utc),
    plan={"id": "pro", "name": "Pro", "interval": "month"},
)

This uses the same opaque user ID as MCP activity and creates the subject locally before sending. Reporting a conversion records one confirmed subscription conversion and sets the SDK lead to subscriber. It does not report upgrades, churn, renewals, billing amounts, currency, customer IDs, subscription IDs, or revenue attribution. Broader lifecycle outcomes can come from a supported CRM connector. The Salesforce connector is upcoming.

Expected first result

After the first successful tool call:

• The tool result returned to the MCP client is unchanged.
• Within receives redacted activity asynchronously.
• Arguments and responses are redacted before send.
• tools/list updates catalog data.
• get_more_tools feedback is stored but excluded from SDK lead scoring.
• Subject activity that reaches the scoring threshold creates or updates an SDK lead.
• The Insights tab can populate Session Replay, Agent Journey Map, Context Explorer, and Missing Tool Demand as relevant activity arrives.