Installation

Northsun meets your agent where it lives. There are three surfaces, and most teams use more than one:

1. CLI — authenticate, look up callers, run recall demos, and inspect API-key status from your terminal.
2. Hosted MCP — connect an MCP-compatible agent without running a local Northsun process.
3. Raw HTTP — use the platform HTTP client for the frozen caller-memory contract while the npm SDK is brought into contract parity.

Get a key

Northsun keys are issued by hand today, not by automated self-serve signup.

Two ways to ask, both real:

• Submit the early-access form. A person issues keys by hand.
• Write through the contact form if you'd rather skip the early-access form.

A key you are issued is a sk_live_ key, and there is no separate activation step after that. It authenticates the REST and MCP examples on this page; the CLI and the kits have their own configuration.

Prerequisites

• Node.js 20.12+ for the CLI.
• A Northsun API key (see "Get a key" above). Hobby is $0; paid tiers are Contact sales. Your tenant is derived from the key — there's nothing else to configure.

Set it once in your shell for the curl examples on this page:

export NORTHSUN_API_KEY="sk_live_…"

1. CLI

The command-line tool authenticates a key, looks up callers, runs an offline demo, and tries a live recall. It is published on npm under its current scope; the Northsun-scoped package name is in progress. Until it ships, the calls it makes work directly over HTTP (see Quickstart); the contact form can supply the current package name.

Available commands: demo (offline sample), login, recall <phone>, caller <phone>, whoami. whoami prints the key (masked), the API base, where the key came from and whether it is valid. Set the API base to https://mcp.northsun.ai; the published release defaults to an earlier hostname that serves the same surface.

See CLI for configuration and output options.

2. MCP server (recommended for agents)

Northsun speaks MCP natively — the transport is built into the API host at https://mcp.northsun.ai/mcp, so there is no local process to install. A separate local stdio package exists in the source repository but is not currently published on npm; use the hosted transport for public setup.

Configure Claude Code (or any MCP client)

Point your client at the hosted HTTP transport. The "type": "http" discriminator is required for an HTTP MCP server entry:

{
  "mcpServers": {
    "northsun": {
      "type": "http",
      "url": "https://mcp.northsun.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${NORTHSUN_API_KEY}"
      }
    }
  }
}

NORTHSUN_API_KEY is required — the same key as the REST API. Restart your client and the Northsun tools appear.

3. TypeScript

Use native fetch for the frozen public REST contract:

const response = await fetch("https://mcp.northsun.ai/v1/recall_and_enrich", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NORTHSUN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+15551234567",
    trigger: "answered",
    session_id: "call_abc123",
  }),
});

if (!response.ok) throw new Error(`Northsun request failed: ${response.status}`);
const recall = await response.json();

A published npm client also exists under its current scope, with the Northsun-scoped name in progress; the examples here use native fetch, which is the supported path. See TypeScript for a small typed HTTP wrapper.

Integration kits for the voice platforms are published on npm under their current scope; the Northsun-scoped package names are in progress. Until they ship, the HTTP calls each kit makes work without it; the contact form can supply the current package names. Vapi and Bland document the calls each kit makes.

Endpoints at a glance

One host. The frozen public v1 surface is POST /v1/recall_and_enrich, POST /v1/calls/end, and GET /v1/caller/{phone_number}.

Verify your install

curl -sS -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $NORTHSUN_API_KEY" \
  "https://mcp.northsun.ai/v1/caller/+15551234567"

200 returns a caller profile; 404 is a valid empty-state result (no such caller in your tenant); 401 means the key or its configuration is wrong.

If you get a 200 or 404, continue to the Quickstart. For language-specific setup, see TypeScript or Python over HTTP.