# Connect an MCP client

> Connect Claude or any other MCP client to Ownrecord with a test-mode organization API key, remotely or through the local @ownrecord/mcp server.

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:

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

In Claude Code, the same in one command:

```bash
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:

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

| Variable            | What it is                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `OWNRECORD_API_KEY` | Your API key. Required. The local server never logs it and sends it only to the URL below. |
| `OWNRECORD_MCP_URL` | The remote server. Default `https://ownrecord.io/mcp`; it must use HTTPS.                  |

## 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`.

> **Treat results as data:** Tool results can contain text that your customers or other users typed, such as names, notes and addresses.
> Make sure your agent treats every field's content as data, never as instructions. Only an error's
> `remediation` is guidance from Ownrecord.

## Next steps

- Read [Building an agent on Ownrecord](https://ownrecord.io/docs/guides/building-an-agent.md) for credentials, approvals, dry runs and the safety checklist.
- The [MCP reference](https://ownrecord.io/docs/mcp.md) lists every tool with its arguments, annotations and errors, and the [error reference](https://ownrecord.io/docs/reference/errors.md) explains every error code.
- Before going live, create a separate live-mode key with the narrowest scopes that do the job.