Get access

Get started · 4 / 42

MCP server

Connect to https://mcp.northsun.ai/mcp over Streamable HTTP with your tenant-scoped API key, then inspect tools/list to pin the tools your client expects.

The hosted Northsun MCP server gives authenticated MCP-compatible agents memory, caller, enrichment, and retrieval tools over Streamable HTTP. Connect to https://mcp.northsun.ai/mcp with the same tenant-scoped API key used by REST.

Configure a hosted connection

The exact configuration filename varies by client, but the connection requires three values:

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

Keep the real key in your client's secret/environment facility. Some clients do not expand ${VARIABLE} placeholders inside JSON; verify how your client resolves secrets rather than committing a literal key.

Anonymous discovery is available at https://mcp.northsun.ai/.well-known/mcp. Tool calls themselves require authentication.

Tool families

The authenticated remote server registers at least the following product tools. Some tools are listed with a name prefix in tools/list: call a tool by the name exactly as listed. MCP evolves independently from the frozen three-endpoint REST surface, so inspect tools/list during integration and pin client expectations.

Frozen caller-memory tools

ToolPurpose
recall_and_enrichRecall a caller and return profile, recent-call memory, and enrichment before a voice interaction.
calls_endPost the completed call transcript and outcome after hangup.
caller_lookupRead a caller profile without creating a caller or triggering enrichment.

Contact workflow tools

ToolPurpose
lookup_contactLook up a contact by phone or email for chat/support workflows.
save_interactionRecord a call, chat, or email interaction.
search_contactsSearch contacts.
get_contact_historyRead prior interactions for a contact.
enrich_contactRequest re-enrichment for an existing contact.
update_contactUpdate supported contact fields.

These tools use authenticated product routes that are not part of the frozen public REST trio. Treat their MCP schemas as the integration contract and re-check tools/list when upgrading.

Governed-context loop

ToolPurpose
observeRecord a voice, chat, or workflow observation for asynchronous memory extraction.
contextRequest a ranked context packet for an entity and query.
feedbackReport which retrieved memories were useful or contradicted.
Memory export toolRetrieve a full tenant-scoped memory export when a prior notification or workflow supplies an entity ID. Its current name is listed by tools/list.

These authenticated MCP tools are the current route for broader voice/chat/workflow context. They do not add public REST endpoints, and their presence does not mean Beacon or proactive delivery is publicly shipped.

Verify the connection

  1. Restart or reload your MCP client.
  2. Inspect the client's tool list and confirm at least caller_lookup, recall_and_enrich, and calls_end appear.
  3. Run caller_lookup with a test number already in your tenant.
  4. A tool call reports a failure in its result text (an error message that includes the upstream status), not as an HTTP status on the connection; for example a lookup of an unknown caller comes back as an error message naming a 404. A missing or invalid key fails the connection with 401.

Hosted versus local

The source repository contains a separate stdio package, but it is not currently published on npm. Public users should use the hosted MCP endpoint. Repository contributors can build the local package from source for development, but should not document an npm install until the package is actually published.

Security boundary

The bearer key establishes the tenant before tools are registered or invoked. Operator-only internal tools are not part of the public product tool list. Never expose your MCP configuration with an embedded key.

Next steps