Skip to main content
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.
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.
API responses are shared with the configured AI client and model. Administrators should connect only an AI provider approved for their production data.

​
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.
The WorkOS organization you sign in with is the default Reach partner. One connection can also act on every other partner whose WorkOS organization you administer, such as a QA or staging account; see Working across partner organizations. Partner routes span the selected partner, while tenant routes require a Reach tenant ID or your external tenant ID. The MCP verifies that the tenant belongs to the selected partner on every tenant-scoped call.

​
Connect your MCP client

Use this remote MCP server URL:

​
Codex

Add the server from a terminal:
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:
Codex normally opens the authorization flow automatically. If authorization is still required, run:

​
Claude Code

Add the server from a terminal:
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 to use by default.
  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 partner list, a guided onboarding prompt, and portable documentation resources.

​
list_partners

Lists the Reach partners whose WorkOS organizations you administer, and marks the one you signed in with. Pass a listed partnerId to execute_reach_api or execute_reach_write to act on that partner. A partner listed with signedIn: false includes a signInUrl; see Sign in to each organization.

​
execute_reach_api

Runs a GET request against a Reach API route. Without partnerId, it acts on the partner you signed in with. With partnerId, it acts on that partner, but only if you are an admin of its WorkOS organization and have signed in to that organization for the MCP. The MCP checks your memberships with WorkOS and never accepts a partner you do not administer. 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 selected 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.
This tool rejects write methods, arbitrary URLs, tenant IDs not owned by the selected partner, and tenant or partner routes outside its reviewed allowlists.

​
execute_reach_write

Runs an approved POST or PATCH request for data onboarding. Provide the partnerId from list_partners, the HTTP method, API path, JSON body, and a concise changeSummary. For a tenant-scoped /api path, also provide tenantId. partnerId is required on every write, even if you administer only one partner. The tool never writes to a default partner, so a write cannot land in production because the target was left out. 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: 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 selected partner before sending the request. For partner operations, omit tenantId.
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.
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.
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 selected partner. Schema deactivation, resource deletion, and configuration writes outside schema definitions and mappings are not available.

​
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. 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.

​
advise_reach_model

Returns versioned product requirements for selected Reach products and business questions. The response separates schemas, fields, mappings, relationships, consent, external prerequisites, and validation cases. It is read-only and only treats source semantics as confirmed when the caller supplies explicit semantic roles. Map each business question to the capabilityIds that deliver it; the tool adds their prerequisites automatically, including prerequisites in another product. Drive the conversation from status: capabilityChoices holds mutually exclusive workflows — a tenant runs one review flow, not all three, and reports in one currency model, not both. The tool returns the options instead of guessing, and withholds any requirement that depends on a choice you have not made. Pick one option per group and pass its capability ID on the next call. Selecting two options from the same group is an error rather than a merged requirement set. Read reach://onboarding/product-capabilities for the catalog index or reach://onboarding/product-capabilities/{product} for a single product pack.

​
Your resource API document

Read reach://docs/partner-resource-openapi for an OpenAPI 3.1 document of the /api/resources endpoints typed with your signed-in partner’s active schema definitions, or reach://docs/partner-resource-openapi/{partnerId} for another partner you administer: request bodies, patch bodies, and responses use your schemas’ fields, and references show the form the API accepts and returns. It reflects schema changes on the next read. For partners with many schemas the document is large, so prefer the per-operation reach://docs/openapi/{operationKey} details when you only need one endpoint.

​
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.

​
Working across partner organizations

If Reach has provisioned separate partner accounts for your QA, staging, and production environments, one connection reaches all of them. Each account must have its own WorkOS organization, and you must hold the admin role in each. Ask the assistant to list them first:
Use reach-developer to list my Reach partners.
Then name the environment in every request, so the assistant passes that partner’s partnerId:
Using our QA partner, list its tenants and schema definitions.

​
Sign in to each organization

The organization you chose when connecting is ready immediately. Every other organization needs its own sign-in before the MCP will act on it, so its SSO, multi-factor, and other sign-in requirements apply exactly as they do in the partner dashboard. The first time the assistant reaches for another organization, the call returns ORGANIZATION_SIGN_IN_REQUIRED with a signInUrl. Open the link, sign in as the same user, and choose that organization. Then ask the assistant to retry; you do not need to reconnect the MCP. Access lasts as long as that sign-in session. When the session expires, or you sign out of it or it is revoked in WorkOS, the MCP stops using the organization until you sign in again. Signing in to the partner dashboard does not count; only the MCP’s own link does.

​
Use a QA partner for onboarding writes

Do onboarding writes and sample records in a QA or sandbox partner account with a dedicated test tenant. A test tenant under your production partner is not isolated: schema definitions and mappings are partner-wide, and validation records can trigger product behavior that the MCP cannot undo. Before making changes:
  1. Ask for list_partners and confirm the QA partner’s name and ID.
  2. Start with a read-only request against that partner and confirm the returned tenants belong to QA.
  3. Approve each write only after confirming the partnerId it targets. Every result names the partner it acted on.
When QA validation is complete, repeat the approved schema and mapping design against the production partnerId. Nothing is promoted between partner accounts automatically.

​
Keeping production out of reach

Access follows your WorkOS account, not the MCP connection: every connection you sign in to reaches every partner whose organization you administer. To make production unreachable from an assistant, sign in with a WorkOS account that is an admin of the QA organization but not of production. If you authorized the wrong organization or account, clear authentication and authorize again. In Codex, run codex mcp logout reach-developer followed by codex mcp login reach-developer. 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.

​
A partner is missing from list_partners

list_partners includes every active WorkOS organization in which you hold the admin role and that Reach has connected to a partner account. Membership changes can take up to five minutes to appear. If a QA or staging partner is still missing, ask your Reach contact to connect its WorkOS organization. The link is tied to the user who connected the MCP and to one organization. Sign in with that same WorkOS account, select the organization the link names, and ask the assistant for a fresh link if it has expired (links last 15 minutes).

​
The client does not open a browser

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

​
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 the selected partner. Ask the assistant to inspect the MCP’s Reach API documentation, or use the API Reference directly. For access or Beta feedback, contact your shared Reach Slack channel or support@embedreach.com.