Introduction

The OnCore MCP server lets an AI coding agent read and change your OnCore configuration on your behalf. Instead of writing API calls, you ask for what you want, and the agent uses a set of tools to do it.

It implements the Model Context Protocol, so it works with any MCP client: Claude Code, Claude Desktop, Cursor, and others. It runs on your own machine as a subprocess of that client, and talks to the OnCore API over HTTPS with your API key.

Two examples of what that looks like in practice. Ask "why did the caller at 3

Install#

You need an OnCore API key. Create one on the API Keys page of your dashboard. See Authentication for the difference between a tenant-level and an organization-level key.

For Claude Code:

claude mcp add oncore -e ONCORE_API_KEY=YOUR_API_KEY -- npx -y @oncore/core-api-mcp

For Claude Desktop, Cursor, and other clients, add this to your client's MCP configuration file:

{
  "mcpServers": {
    "oncore": {
      "command": "npx",
      "args": ["-y", "@oncore/core-api-mcp"],
      "env": {
        "ONCORE_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Restart the client, then ask it to call whoami. That reports which environment it reached, which kind of key it is using, whether writes are enabled, and every capability it deliberately does not have. It is the fastest way to confirm the install and the last thing worth checking when something behaves unexpectedly.

Node.js 20 or newer is required. npx fetches the package on first run, so there is nothing to clone and nothing to build.

Configure#

One variable is required. The rest have defaults chosen so a normal install needs no configuration.

A tenant-level key already identifies its tenant, and the API ignores any tenant sent alongside it. So setting ONCORE_TENANT_ID with a tenant key is refused at startup rather than quietly ignored: a configuration that claims a scope it does not have is worse than one that fails immediately.

Configuration problems are reported before the client finishes connecting. The server prints one line per problem and exits, so a wrong value shows up as a readable message in your client's logs rather than as a tool call that fails later.

Which key to use#

A tenant-level key is the simpler and safer choice. It reaches exactly one tenant, and the API derives that tenant from the key itself, so the agent has no way to reach another one regardless of what it asks for.

An organization-level key plus ONCORE_TENANT_ID is for developers who manage several tenants. The tenant you name is checked against your organization on every request. To work across several tenants, register the server once per tenant under different names; your client can run them side by side and will keep the tools separate.

What it does not do#

Some operations are unreachable by design rather than merely undocumented, so there is no flag that turns them on:

• Anything administrative, including the endpoints that create or read API keys.
• Releasing a phone number, because the carrier release cannot be undone.
• Buying a phone number, because it is a recurring charge and stays a deliberate human action.
• Anything acting on a call in progress: no ending it, no taking it over, no listening in.
• Anything that starts a metered session, such as an outbound web call or a WhatsApp onboarding.
• Starting a test run, which is a metered simulation. The agent prepares suites and reads the results; you start runs in the dashboard.

Ask whoami for the current list with the reason attached to each one.

Next steps#

• Tools and write safety covers what the agent can read and change, and how confirmation works.
• Authentication explains API keys and tenant scope in full.
• Errors documents the error shapes the tools surface back to the agent.