> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedreach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reach Developer MCP (Beta)

> Connect an AI coding assistant to the Reach partner API

<Warning>
  The Reach Developer MCP is in **Beta**. Its endpoint, available capabilities, and client compatibility
  may change before general availability. Do not make it a production dependency.
</Warning>

The Reach Developer MCP lets an AI coding assistant explore your Reach
integration using partner-wide operations and tenant-scoped operations for
tenants your organization owns. It is useful during onboarding for inspecting
tenants, schemas, mappings, resource counts, channel integrations, and product
configuration.

Most MCP operations are read-only. A separate write tool supports the schema and sample-resource operations used during data onboarding. Write requests remain subject to the AI client's approval controls. The MCP cannot delete Reach data.

<Warning>
  API responses are shared with the configured AI client and model. Administrators should connect only an
  AI provider approved for their production data.
</Warning>

## Before you connect

You need:

* A Reach partner account with a WorkOS organization connected by Reach
* The `admin` role in that WorkOS organization
* An MCP client that supports remote HTTP servers and browser-based OAuth

You do **not** need to copy a Reach API key or JWT secret into the MCP client.
Authentication happens through WorkOS AuthKit in your browser.

<Note>
  The selected WorkOS organization determines the Reach partner. Partner routes span that partner, while
  tenant routes require a Reach tenant ID or your external tenant ID. The MCP verifies that tenant
  belongs to the authenticated partner on every tenant-scoped call.
</Note>

## Connect your MCP client

Use this remote MCP server URL:

```text theme={null}
https://mcp.embedreach.com/mcp
```

### Codex

Add the server from a terminal:

```bash theme={null}
codex mcp add reach-developer --url https://mcp.embedreach.com/mcp
```

<Note>
  This command adds the server to your global Codex configuration. To limit the connection to one
  trusted repository, add it to `.codex/config.toml` in that repository instead:

  ```toml theme={null}
  [mcp_servers.reach-developer]
  url = "https://mcp.embedreach.com/mcp"
  ```
</Note>

Codex normally opens the authorization flow automatically. If authorization is
still required, run:

```bash theme={null}
codex mcp login reach-developer
```

### Claude Code

Add the server from a terminal:

```bash theme={null}
claude mcp add --scope user --transport http reach-developer https://mcp.embedreach.com/mcp
```

The `user` scope makes the connection available across your local projects and
worktrees. To keep it private to the current project, use `--scope local`
instead. Start Claude Code, run `/mcp`, and authenticate `reach-developer` in
your browser.

### Other MCP clients

1. Add a remote or streamable HTTP MCP server.
2. Enter `https://mcp.embedreach.com/mcp` as the server URL.
3. Choose OAuth authentication if the client asks for an authentication method.
4. Sign in through WorkOS and select the partner organization you want to use.
5. Approve the connection.

The client discovers the OAuth configuration from the MCP server. Do not enter
a client secret or manually create a bearer token.

## What your assistant can use

The MCP exposes two action tools, a guided onboarding prompt, and portable documentation resources.

### `execute_reach_api`

Runs a GET request against a Reach API route. The MCP chooses the partner from
the verified WorkOS organization; the model cannot provide or override the
partner ID.

For a partner-wide `/partner` path, provide only `path`. For a tenant-scoped
`/api` path, also provide `tenantId`, using either the Reach tenant ID or the
external tenant ID configured by your platform. The MCP validates the tenant
against the authenticated partner and supplies the `reach-tenant-id` header.

Available operations include:

* Approved tenant-scoped GET routes under `/api`
* Approved partner-wide GET routes for tenant records
* Approved partner-wide GET routes for schemas, mappings, resource counts,
  channel integrations, and aggregate Voice reporting

The MCP also publishes Reach API and integration documentation as resources so
your assistant can look up an endpoint before calling it.

<Info>
  This tool rejects write methods, arbitrary URLs, tenant IDs not owned by the authenticated partner, and
  tenant or partner routes outside its reviewed allowlists.
</Info>

### `execute_reach_write`

Runs an approved `POST` or `PATCH` request for data onboarding. Provide the
HTTP `method`, API `path`, JSON `body`, and a concise `changeSummary`. For a
tenant-scoped `/api` path, also provide `tenantId`.

Replacing partner schema mappings also requires `ifMatch`. First read
`GET /partner/schema-mappings` with `execute_reach_api`, then pass the returned
`etag` value unchanged. If the mappings changed in the meantime, Reach rejects
the replacement so you can read them again and review a fresh diff.

The current write allowlist is:

| Scope   | Method  | Path                                                     | What it allows                                             |
| ------- | ------- | -------------------------------------------------------- | ---------------------------------------------------------- |
| Partner | `POST`  | `/partner/schema-definitions`                            | Create a schema definition                                 |
| Partner | `POST`  | `/partner/schema-definitions/{schemaIdOrName}`           | Update an existing schema definition by ID or name         |
| Partner | `POST`  | `/partner/schema-mappings`                               | Replace the complete partner schema mappings configuration |
| Tenant  | `POST`  | `/api/resources/{schemaDefinitionNameOrId}`              | Create or upsert one schema-defined resource               |
| Tenant  | `POST`  | `/api/resources/{schemaDefinitionNameOrId}/batch`        | Submit an asynchronous resource create or upsert batch     |
| Tenant  | `PATCH` | `/api/resources/{schemaDefinitionNameOrId}/{externalId}` | Patch one resource by external ID                          |
| Tenant  | `PATCH` | `/api/resources/{schemaDefinitionNameOrId}/batch`        | Submit an asynchronous resource patch batch                |

For tenant operations, `tenantId` is required and may be either the Reach
tenant ID or your external tenant ID. The MCP verifies that the tenant belongs
to the authenticated partner before sending the request. For partner
operations, omit `tenantId`.

<Warning>
  Schema mappings are replaced as one complete configuration. Read the current mappings first, review a
  full before-and-after diff, and send the complete resulting configuration. Omitting an existing mapping
  removes it.
</Warning>

The Developer MCP applies narrower limits than the underlying Reach API:

* The JSON body may be no larger than 100 KiB (102,400 bytes).
* A batch body may contain no more than 100 resources.
* `changeSummary` is required, may contain up to 500 characters, and should not
  contain credentials or sensitive record values.
* Only the method and path combinations in the table above are accepted. In
  particular, schema updates use `POST`, while individual and batch resource
  patches use `PATCH`.

Use the Reach API directly for production synchronization and historical
backfills. Batch submission returns before processing finishes; use
`execute_reach_api` to poll `/api/batches/{batchId}` and inspect validation
errors.

<Info>
  No other write routes are exposed. The tool rejects `GET`, `DELETE`, arbitrary URLs, unreviewed `POST`
  or `PATCH` routes, and tenant IDs not owned by the authenticated partner. Schema deactivation, resource
  deletion, and configuration writes outside schema definitions and mappings are not available.
</Info>

### `onboard_reach_data`

Clients that support MCP prompts can start this guided workflow with an optional validation tenant, source-system description, and onboarding objective. The prompt directs the assistant through source-model discovery, schema and mapping review, approved writes, small record tests, asynchronous batch diagnostics, and raw resource reconciliation.

The detailed workflow is also published as the portable `reach://docs/guides/onboarding-developer-mcp-data-onboarding` resource. Clients that do not expose MCP prompts can read that resource directly or use the [Developer MCP Data Onboarding guide](/onboarding/developer-mcp-data-onboarding). Keeping the procedure in a resource makes the same versioned guidance available to agents, developers, and documentation readers; the prompt remains a short entry point.

## Example prompts

* “Use the Reach Developer MCP to list my tenants.”
* “For tenant `acme-location-42`, list its segments and summarize how they are configured.”
* “Show the schema definitions configured for this partner.”
* “Summarize resource counts by tenant without listing individual records.”
* “Read the Reach API documentation and explain how schema mappings work.”
* “Show aggregate Voice call activity for the last seven days.”
* “Create these approved schema definitions, install the reviewed mappings, and validate three synthetic records for tenant `acme-test`.”

Your assistant may ask permission before invoking the tool, depending on the
client's tool-approval settings.

## Switching between partner organizations

An OAuth grant is scoped to one WorkOS organization. If Reach has provisioned
separate partner accounts for your development, staging, and production
environments, create one named MCP connection per environment. All connections
use the same MCP URL; the name and OAuth authorization keep their credentials
and tools distinct.

Use names that make the target environment unmistakable, such as
`reach-development`, `reach-staging`, and `reach-production`.

### Codex

```bash theme={null}
codex mcp add reach-development --url https://mcp.embedreach.com/mcp
codex mcp login reach-development

codex mcp add reach-production --url https://mcp.embedreach.com/mcp
codex mcp login reach-production
```

Complete each browser flow separately and select the WorkOS organization that
matches the connection name.

### Claude Code

```bash theme={null}
claude mcp add --scope user --transport http reach-development https://mcp.embedreach.com/mcp
claude mcp add --scope user --transport http reach-production https://mcp.embedreach.com/mcp
```

Start Claude Code, run `/mcp`, and authenticate each connection separately.
Select the WorkOS organization that matches its connection name. If the tools
do not appear immediately after authorization, restart the client.

### Target an environment

Name the connection in your prompt so the assistant uses the intended tool
namespace:

> Use `reach-development` to list the partner's tenants and schema definitions.

Before making changes, start with a read-only request and confirm that the
returned tenants belong to the expected environment. Prefer a development or
sandbox connection for onboarding writes and sample records.

Each connection remains isolated: requests made with one organization's token
resolve only to the Reach partner mapped to that organization.

If you authorized the wrong organization, clear authentication for only that
connection and authorize it again. In Codex, run:

```bash theme={null}
codex mcp logout reach-development
codex mcp login reach-development
```

In Claude Code, run `/mcp`, select the connection, and choose **Clear
authentication** before authenticating again.

## Troubleshooting

### The organization is rejected

Confirm that:

* You selected the intended WorkOS organization.
* Your membership role in that organization is `admin`.
* Reach has connected that WorkOS organization to the expected partner account.

### The client does not open a browser

Use the client's OAuth login or reconnect action. For Codex, run:

```bash theme={null}
codex mcp login reach-developer
```

### A requested API path is unavailable

The Beta MCP exposes reviewed sets of tenant-scoped and partner-wide GET routes.
For a tenant-scoped path, confirm that it is listed in the MCP's API resources,
that you supplied the intended Reach tenant ID or external tenant ID, and that
the tenant belongs to this partner. Ask the assistant to inspect the MCP's
Reach API documentation, or use the [API Reference](/api-reference/introduction)
directly.

For access or Beta feedback, contact your shared Reach Slack channel or
[support@embedreach.com](mailto:support@embedreach.com).