Beacon's MCP server, for engineers

How it sits

The agent is not a model. It’s a transport. It receives tool calls from an MCP client, validates them, and forwards them to Beacon’s existing API. The model lives in your AI assistant. The product lives in Beacon. The MCP server is the layer in between that speaks both protocols.

If you’ve integrated with Beacon’s REST API directly, you’ve integrated with the same engine. The MCP server exposes a subset of that surface, shaped for tool-calling, and adds the constraints described below.

The boundary

The MCP server process has no Zendesk credentials. It cannot construct a Zendesk API request. It has a Beacon client and an MCP server. Every call from the AI assistant resolves to a Beacon API call, authenticated as the user who connected the MCP server.

This isn’t a runtime check that can be relaxed by a config flag. The process doesn’t link against a Zendesk SDK. Removing this boundary would mean shipping a different binary.

For the longer architectural argument behind this design, see Why you don’t want a direct-to-Zendesk MCP.

The tool model

Tools fall into two groups.

Read tools. Things like list_triggers, describe_view, compare_snapshots, find_dependencies. These resolve to Beacon read operations against the most recent configuration snapshot Beacon has captured. They produce no Zendesk side effects. Every response carries a snapshot_meta block with the snapshot id, its creation time, and its age in seconds, so the agent can judge freshness.

Plan tools. Things like promote_cross_instance and the change-builder tools for same-instance edits. These take a desired change and return a structured plan: the set of operations Beacon would perform, the dependencies, the before-states, the predicted result. A plan is a value, stored as a PromotionPlanRecord keyed by UUID with a 72-hour TTL, consumed at most once.

Apply tools, scoped by target. Whether an apply tool can run depends on the target connection’s agent_write_policy:

• sandbox target: apply_promote runs through the MCP client. The plan token is the same one returned by the planner; the agent calls apply_promote(plan_token, confirm=true) and Beacon executes the existing apply engine.
• production target: there is no MCP apply path. The planner returns approval_required: true and an approval_url to Beacon’s web app (/mcp/approvals/<uuid>). The agent calling apply_promote on a production-target plan gets a production_requires_human_approval error. The human reviewer follows the URL, authenticates against the Beacon web app, and clicks Approve. Self-review is blocked: the reviewer must be a different account from the API key owner who minted the plan. Editor access on the target connection is enforced by the same access function the human-driven /promote/v2/push route already uses.
• none: writes not enabled for that connection. The planner refuses to even store a plan.

The agent learns the outcome through get_promote_status(plan_token), which derives status from the plan record (consumed_at, rejected_at, expires_at) and returns the rollback token if the apply succeeded.

Authentication

The user mints an MCP API key in Beacon (Settings → API keys, MCP scope). Tokens carry the bk_ prefix; what marks a key as an MCP token is its scope, not the prefix. Three scopes:

• mcp_read: read tools only.
• mcp_write_sandbox: adds sandbox-target write tools and cross-instance promotion targeting a sandbox connection.
• mcp_write_production_class: adds cross-instance promotion targeting a production connection (still gated by the human-approval flow described above).

Both write scopes require a non-empty connection allowlist at mint time. There are no wildcard write keys. mcp_write_production_class can only be minted if the account actually owns at least one production-class connection.

Tokens are per-user, revocable from the Beacon UI, and effective immediately on revocation: any tool call made with a revoked key returns auth_required. Every tool call (success, error, or denial) is recorded in Beacon’s audit log scoped to the API key’s owning account.

Multi-user behaviour: each user mints their own MCP key. The agent acts as that user, with that user’s Beacon permissions and connection allowlist. There is no shared service account.

Audit

Every MCP tool call is logged in Beacon. Each entry records the user account the credential resolves to, the AI assistant’s identity (insofar as the client identifies itself), the tool name and arguments, the resulting plan if any, the eventual approval and apply if the plan is applied, and the rollback token issued on apply.

The log is the same log Beacon writes for every other API call. Agent-driven actions don’t go to a separate stream. This matters for compliance pipelines that already ingest Beacon’s audit.

Rate limiting and abuse

Per-credential rate limits apply, separately from Zendesk’s own API limits. Repeated plan generation against the same operation is fine and expected (the agent often plans, learns, replans). Repeated apply requests against the same plan are not: a plan is single-shot, identified by hash, and refused if already applied.

The credential can be revoked from Beacon at any time. Revocation is immediate. In-flight tool calls are rejected on the next operation.

What the assistant sees vs what it gets

This matters for prompt-injection thinking. The agent returns structured plans as tool results. The plans include human-readable descriptions, but the descriptions are derived from the structured operations, not free-form text the agent invented. If a plan’s structured operation list is empty, no apply will do anything, regardless of what the description says.

In practice this means a prompt-injection attempt that lands in (say) a ticket’s content can’t end up driving a configuration change, because the MCP server doesn’t read tickets. It only reads configuration. If a configuration object contains an attacker-controlled string and the agent describes it back, the description is the only thing the assistant sees; it does not become an instruction Beacon honours on apply.

This isn’t a complete answer to prompt-injection risk. It’s the part of the answer that’s in the architecture. The remaining part is your AI assistant’s safety model, which is the part we don’t ship.

Versioning

The MCP tool schema is versioned. Tool removals and breaking argument changes increment the major. Additions are minor. We publish a changelog and ship the previous major for at least one full release cycle alongside the new one.

Zendesk object support tracks Beacon’s. When Beacon learns to handle a new object type, the MCP server gains corresponding read and plan tools in the same release.

Where to go from here

The MCP protocol itself is documented at modelcontextprotocol.io. Beacon’s own API reference, the quickstart for connecting an AI assistant, and the security overview for review live in the Beacon app and we’ll share them on request.

If you’re integrating the MCP server into an internal AI tooling stack, we’re happy to walk through the architecture on a call. We’ve done this with a few teams already and there are usually questions that need an engineer on both ends.