Connect an MCP client

Ownrecord runs a remote MCP server at https://ownrecord.io/mcp. Its tools are generated from the same operations as the REST API, so an agent can do through MCP what an API key can do through REST, with the same permission checks, idempotency, dry runs and audit log. This guide connects a client with an organization API key in test mode, so nothing your agent does touches live data.

1. Create a test-mode organization key#

In the console, switch to test mode, open Developers → API keys and create a key:

• Kind: organization. An organization key can use management tools such as creating brands, and acts on any entity or brand of your organization. Brand and entity keys work too, limited to their brand or entity.
• Scopes: only what the agent needs, for example brands:write to create brands and keys:read to list keys.

The key starts with or_test_ and is shown once. Keep it in your client's secret store, never in a prompt.

2. Add the server to your client#

If your client supports remote MCP servers with custom headers, point it at the server and send the key as a bearer token:

{
  "mcpServers": {
    "ownrecord": {
      "type": "http",
      "url": "https://ownrecord.io/mcp",
      "headers": {
        "Authorization": "Bearer or_test_…"
      }
    }
  }
}

In Claude Code, the same in one command:

claude mcp add --transport http ownrecord https://ownrecord.io/mcp --header "Authorization: Bearer or_test_…"

If your client only runs local servers, use the @ownrecord/mcp package (Node.js 20 or later). It starts a local stdio server that forwards every tool list and tool call to the remote server:

{
  "mcpServers": {
    "ownrecord": {
      "command": "npx",
      "args": ["-y", "@ownrecord/mcp"],
      "env": {
        "OWNRECORD_API_KEY": "or_test_…"
      }
    }
  }
}

3. Try it#

Ask your agent to list the Ownrecord tools, then to create a brand in test mode. A good agent does it in two steps:

1. it calls the brand creation tool (brands_create) with dry_run: true, which checks permissions and rules and shows the result without saving anything;
2. it calls it again without dry_run, with an idempotency_key, and the brand is created.

Every tool that changes data returns the idempotency_key it used. When the server generates one because the agent sent none, the agent can retry with it: the same key and arguments never act twice.

With an organization key, brand-level tools need a brand_id and entity-level tools an entity_id to say where to act, like the Ownrecord-Brand and Ownrecord-Entity headers of the REST API. Brand keys act on their own brand without one.

What your agent gets back#

A successful call returns the operation's output exactly as the REST API does, amounts in integer micros as strings and dates in ISO 8601, with the request_id and, for changes, the idempotency_key. Lists return one page with next_cursor. A refused call returns a tool error with a stable code, a message, a remediation that says what to do next, a docs_url and retryable.

Next steps#

• Read Building an agent on Ownrecord for credentials, approvals, dry runs and the safety checklist.
• The MCP reference lists every tool with its arguments, annotations and errors, and the error reference explains every error code.
• Before going live, create a separate live-mode key with the narrowest scopes that do the job.