External MCP

External MCP lets another local application—such as Codex, Claude Code, Claude Desktop, or another MCP-capable client—create and follow restricted Tejus tasks through a connection you approve in Tejus.

It is separate from the internal Agent Gateway injected into supported provider sessions already running inside Tejus.

Internal gateway or external connection

Use External MCP when work begins outside Tejus but should execute through Tejus’s durable task and worktree pipeline. Tejus must be running on the same computer: the external client talks to it through a local bridge process.

Create the connection

The generated setup is preferred because it uses the exact executable and data directory of the running Tejus installation. It does not require you to guess a command, project ID, model slug, request ID, or credential path.

Set up by hand

For apps without a terminal or chat (for example Claude Desktop), open Set up by hand instead → Show. It shows two copy-ready blocks:

1. Pairing command (run in Terminal) — run it once in PowerShell. It exchanges the one-time code for a private credential stored on this computer.
2. MCP configuration (JSON) — merge it into the app’s MCP configuration. In Claude Desktop: Settings → Developer → Edit Config, add the tejus entry without removing existing servers, save, and restart Claude Desktop.

Always copy the commands from Tejus. On Windows they have this shape (paths and IDs are filled in for your installation):

$env:ELECTRON_RUN_AS_NODE = '1'; & '<path to tejus.exe>' '<Tejus server entry>' 'mcp' 'pair' '--code' '<one-time code>' '--home-dir' 'C:\Users\<you>\.tejus'

{
  "mcpServers": {
    "tejus": {
      "command": "<path to tejus.exe>",
      "args": [
        "<Tejus server entry>",
        "mcp",
        "serve",
        "--integration",
        "<integration id>",
        "--home-dir",
        "C:\\Users\\<you>\\.tejus"
      ],
      "env": { "ELECTRON_RUN_AS_NODE": "1" }
    }
  }
}

ELECTRON_RUN_AS_NODE=1 lets the Tejus executable run the bridge as a plain command-line process instead of opening a second app window. --home-dir is your Tejus data folder (%USERPROFILE%\.tejus, or the folder set by SYNARA_HOME).

The setup prompt also contains ready-made registration commands for the two most common clients:

# Codex
codex mcp add tejus --env ELECTRON_RUN_AS_NODE=1 -- <command> <args...>

# Claude Code (available in all your projects)
claude mcp add --scope user tejus -e ELECTRON_RUN_AS_NODE=1 -- <command> <args...>

Do not copy a configuration from another Tejus installation without updating its executable and home directory. The bridge intentionally fails rather than silently connecting to an ambiguous or unsafe instance.

How the bridge finds Tejus

The mcp serve bridge reads the running server’s address from the private runtime file userdata\server-runtime.json inside the home directory, then proves with a fresh challenge that the process answering is the Tejus instance named by that file before forwarding any credential or pairing code. On Windows the bridge refuses a runtime file that is not owned by your account, is accessible by other users, or is a reparse point.

The paired credential is stored in mcp\credentials\<integration id>.json under the home directory. The MCP client configuration contains only the bridge command and integration identifier, never the raw credential.

Pairing lifecycle

If a pairing code expires or the page reloads, use Resume pairing to issue a fresh code without replacing the connection. For an already paired connection, Continue setup in Connected agents restores the setup instructions.

A new pairing code does not replace a previously paired credential automatically. If an integration already has a different stored credential, revoke it in Tejus before pairing again.

External tool surface

The advertised tool catalog is filtered by the connection’s granted scopes. It can include:

• tejus_overview — allowed projects (with on-disk paths), provider availability, scopes, defaults, limits, activity, and suggested next steps
• tejus_capabilities — valid provider/model construction and safety limits for an allowed project
• tejus_list_allowed_projects — only projects granted to the connection
• tejus_create_task — one durable task for one stable requestId
• tejus_wait_for_task — wait for an authorized task without changing it (30 seconds by default, at most 60)
• tejus_read_task — read tasks owned by the connection, with broader project reads requiring Read other project tasks

External MCP intentionally exposes a smaller surface than the internal Agent Gateway.

Create a task safely

Task creation requires an explicit:

• projectId
• Provider
• Model
• Prompt
• Stable requestId

Safe defaults are:

• Managed worktree environment
• Approval-required runtime mode

Use tejus_overview and tejus_capabilities first. Do not guess IDs, model slugs, or option shapes.

A stable request ID makes retry behavior durable:

• Reusing it with the same plan replays the existing result
• Reusing it with a different plan is rejected
• An ambiguous client response should be retried with the same ID after reading current state

Do not generate a new request ID merely because the first response was lost.

Project and task ownership

A connection can create tasks only in projects it is allowed to use.

By default, it reads tasks it created. Reading other tasks in an allowed project requires Read other project tasks.

Keep connections narrow:

• A CI assistant may need one repository
• A personal coding client may need several selected projects
• A general local orchestrator may need all projects, but still should not receive unnecessary full-access or local-checkout authority

Limits and active task slots

Each connection has project, capability, rate, and active-task limits. New connections allow 60 requests per minute and 2 active tasks at a time.

An active slot is reserved while task creation is in progress and remains occupied while the owned task’s current turn is pending or running. Idempotent retries of the same request do not consume another slot.

When a limit is reached, inspect active tasks and finish, interrupt, or wait for them. Do not create additional connections to evade an intentional safety limit.

Security model

External MCP is designed for local use:

• The external endpoint only answers a loopback-only Tejus instance on this computer.
• Credentials use a fixed external-MCP audience and cannot authenticate browser, WebSocket, internal provider-session, or general server-token paths.
• Credentials expire (30 days) and are revocable.
• Tejus stores credential hashes in its database rather than raw server-side credentials.
• The bridge verifies the running local instance with a fresh challenge before forwarding credentials or pairing codes.

On Windows, the local credential file stays under your user profile but does not get a POSIX permission check. Protect the Windows account and the .tejus data folder accordingly.

Audit and privacy

Audit rows can record:

• Connection identity
• Tool name
• Request ID
• Project
• Environment and runtime mode
• Outcome
• Created task IDs

Full prompts are not copied into audit rows or durable recovery plans.

Still treat prompts as sensitive application data. Do not place secrets in them merely because the audit layer omits their full text.

Revocation

Revoke a connection from Settings → MCP connections → Connected agents → Revoke (or Revoke and start over during setup). Its credential stops working immediately, including for continuing long-running operations. Create and pair a new connection rather than trying to reuse a revoked credential.

Also revoke a connection when:

• The external client or machine is no longer trusted
• Project access should be reduced
• A credential file may have been copied
• The connection was created for a temporary workflow
• You no longer understand why it needs its current scopes

Failure handling

Waiting for pairing never completes

Use Resume pairing, confirm Tejus is still running, and give the agent the refreshed setup prompt. Do not manually paste raw credentials into the client configuration.

Paired but not connected

The client has a credential but has not successfully called the bridge. Verify the generated command, executable paths, home directory, and local client logs, then reload the client’s MCP servers.

The wrong projects appear

Review the connection’s selected projects and scopes. tejus_list_allowed_projects should never return projects outside that grant.

Task creation is rejected

Read tejus_overview and tejus_capabilities. Check project access, provider availability, model selection, active-task limits, and whether the requested environment or runtime mode requires an ungranted scope.

A retry conflicts with the request ID

The new plan differs from the original durable request. Use the original plan or create a new intentional request ID after confirming you want a distinct task.

“No running Tejus instance was found”

Start Tejus, or pass the --home-dir of the intended installation. If the bridge reports multiple running instances, stop one or give each a distinct --home-dir. The bridge will not guess between ambiguous local runtimes.

The runtime file is refused on Windows

The bridge reports that server-runtime.json is not owned by the current user or is accessible by other users. Run the client as the same Windows user that runs Tejus, and do not loosen permissions on the .tejus folder.

The credential is revoked or expired

Create and pair a new connection. Do not weaken validation or modify the credential file to bypass lifecycle checks.

External MCP checklist

• The connection has a clear purpose and owner
• Only required projects are allowed
• Managed worktree and approval-required defaults are preserved where possible
• Advanced permissions are individually justified
• Generated setup uses the intended Tejus installation
• tejus_overview verifies the connection
• Stable request IDs are reused for retries
• Created tasks and active slots are monitored
• Audit information and prompts are treated appropriately
• Temporary or untrusted connections are revoked