External connections

Connections are how Mogplex agents reach external systems.

They are separate from managed model access, GitHub App coverage, Slack channel links, and the live endpoint where other MCP clients call into Mogplex.

Open ConnectionsCopy Anchor Link

Select Connections in the app sidebar. The page lives at /<scope>/connections and has two tabs:

• Integrations contains service presets, saved connections, the custom connection form, and Slack setup.
• MCP Servers manages saved servers for web chat and the Mogplex CLI.

The MCP Servers tab uses /<scope>/connections?tab=mcp. Reloads and browser Back preserve the selected tab.

Connections belong to your personal account. Shared team connections are not available yet. In a team scope, select Open personal connections to manage your own services.

Old Settings links with ?tab=connections or #connections still work. OAuth and Slack return messages follow the redirect to the new page. The old /<scope>/settings/mcp page and Settings links with ?tab=mcp or #mcp open the MCP Servers tab.

Use a saved server in web chatCopy Anchor Link

Here, web chat means workspace chat and Control in the app.

Choose Add server and leave Streamable HTTP selected. Enter the server URL and any required headers. Save the server with Enabled on. Its tools become available on the next web chat or Control turn without a separate Integration. The server must support Streamable HTTP and have a public URL. Saved secret headers stay hidden in the browser. Mogplex sends them to the configured MCP server when it connects.

Local (CLI only) uses stdio to start a process on your computer. Local HTTP addresses also remain CLI-only. Web chat cannot reach your computer's local servers.

Disable or delete a saved server to exclude its tools from subsequent turns. Servers stay private to the account that created them. In team scope, owners, admins, and developers can use their own saved servers. Viewers cannot use connection tools. Saved allowlists, blocklists, and per-tool restrictions also apply to chat. Tools that need approval require Control, which can ask before a call. Workspace chat, the Slack agent, and native-harness runs withhold these tools because they cannot ask.

Test a saved connectionCopy Anchor Link

Choose Test connection on a saved HTTP server. The test reads its saved URL and headers, then lists tools. It does not run tools. The result shows the tool count, workspace chat availability, tools that require Control approval, and blocked tools. Expand Discovered tools to inspect each tool's effective permission.

An error explains whether to check the public URL, authorization headers, missing secrets, invalid permission fields, or server response time. A manual test allows six seconds for discovery. Closing the connection can add up to two seconds. A slow close does not turn a successful test into a failure. This cleanup budget applies only to the manual test, not chat startup. A successful connection with no tools shows a count of zero. The test also checks disabled servers. Enable a server before its allowed tools become available. Test local stdio servers through the CLI.

Enabled records a setting, not connection health. Results describe the last manual test during the current page visit. They reset after saved settings change or the page reloads. Tests do not run automatically or monitor server health. Chat still discovers tools at the start of each turn, so availability can change after a test.

Set tool permissionsCopy Anchor Link

Choose Edit on an HTTP server and find Tool permissions. The Integrations approval menu applies only to Integration entries.

Test the saved connection before an edit to populate its tool names. Add tool rule also accepts an exact name without a test. For a tool marked Disabled in saved settings, turn on the switch beside that label to enable it. Other block rules still apply.

Save changes to apply them on the next turn. The controls preserve unrelated CLI fields and permissions. The form only saves valid permission values. If an earlier CLI or manual edit left an invalid policy, the structured controls cannot edit it. Open Extra JSON, correct the invalid fields, then save. Mogplex withholds tools from invalid policies until you fix them.

Without an explicit approval mode, saved tools run automatically, like Integrations in web chat. CLI approval defaults remain unchanged. Other CLI-specific extra options do not configure web chat.

The controls use the same fields as Extra JSON. Advanced edits remain available. Run automatically maps to auto, Ask in Control to prompt, and per-tool Block to deny. Allowed tools sets enabled_tools. Blocked tools sets disabled_tools. The switch beside Disabled in saved settings sets tools.<name>.enabled to true. For example, this JSON allows search and publish, blocks delete, and asks before publish in Control. Replace these example names with the tool names your server exposes.

{
  "enabled_tools": ["search", "publish", "delete"],
  "disabled_tools": ["delete"],
  "default_tools_approval_mode": "auto",
  "tools": {
    "publish": { "approval_mode": "prompt" }
  }
}

delete appears in both lists to show that the blocklist wins. The allowlist limits which tools can load. The blocklist and per-tool enabled: false exclude tools even if the allowlist includes them. A per-tool approval mode overrides the default. auto and approve both allow automatic calls. A server-level default of prompt makes every tool without a per-tool override Control-only. Per-tool deny excludes a tool. prompt requires a Control approval card. Workspace chat, the Slack agent, and native-harness runs withhold these tools.

Direction mattersCopy Anchor Link

There are three MCP-related surfaces with different directionality:

When a hosted run cannot call an external tool, debug Connections. When another agent host needs to call Mogplex directly, install the Mogplex MCP endpoint. Use Skills when the host needs guidance for driving the CLI instead of direct MCP tools.

Connection typesCopy Anchor Link

Mogplex supports two connection categories:

Manual auth modes include none, API key, bearer token, basic auth, and OAuth. Connection credentials are stored server-side and resolved only when the connection is tested, listed for CLI sync, or used by a run.

Quick-add presetsCopy Anchor Link

Connections includes MCP presets for common tool providers:

Some presets use direct credentials. Some use OAuth, including managed auth where Mogplex brokers the provider flow.

How the Trigger preset worksCopy Anchor Link

One Trigger.dev Personal Access Token gives agents two things.

API tools that need no sandbox. Control's coordinator, workspace chat, the Slack agent, and runs on the native Mogplex harness get the Trigger.dev management API as tools, read and write, called directly from Mogplex servers:

Three things are deliberate:

• Every write names its environment. Reads default to prod, but a task never fires, and a schedule never changes, in production because a field was left out.
• Environment variable values are never returned. Agents see names and can set values, but a value you stored in Trigger.dev does not come back into a conversation.
• Your token stays on Mogplex servers. Where Trigger.dev accepts one, a call uses a short-lived token scoped to that single operation, the same exchange the official MCP server performs. The remaining management routes only accept an environment key, which Mogplex reads with your token for the length of the turn and never shows to the agent.

The full MCP server next to your code. Trigger.dev publishes its MCP server as a local command, not a hosted URL, and tools such as deploy and start_dev_server need your project files. Mogplex starts it where the code is:

• In a sandbox, the Claude Code harness launches npx -y trigger.dev@latest mcp with your token set as TRIGGER_ACCESS_TOKEN.
• In the Mogplex CLI, the same command arrives with your other synced MCP servers.

To add it, create a Personal Access Token at cloud.trigger.dev/account/tokens (the preset links there) and paste it in. It starts with tr_pat_. Test confirms that Trigger.dev accepts the token and reports the API tool count; it does not start the MCP server. Mogplex fixes the command in the preset, so nothing you type is ever executed.

Use presets first when one exists. Use manual Add Connection for advanced MCPs or REST APIs that do not have a preset yet.

Where connection tools loadCopy Anchor Link

The Control row is the coordinator, the agent you talk to. A worker it delegates to is a sandbox run, so it follows the row for its harness.

These saved servers belong to the user and apply across repos. Integration scope exclusions do not apply to this separate catalog.

Control waits up to eight seconds for remote MCP servers, including saved servers, when a turn starts. If one is slow or down, the turn runs without connection tools instead of hanging. Saved-server discovery uses a six-second startup budget, leaving time to return healthy tools before Control's deadline. A server that misses that deadline is left out. The deadline does not cancel later tool calls on servers that loaded successfully.

Asking before a connection's tools runCopy Anchor Link

This section describes Integrations. For saved MCP Servers, use Tool permissions.

By default, tools from Integrations run without asking. You can change that per connection: open the connection's menu in Connections (or the auto control on a row in the Connections pane) and choose Ask before running tools. The row then shows asks first.

Choose Run tools without asking to switch back.

Scope resolutionCopy Anchor Link

Integrations can be global or project-scoped. Saved MCP Servers apply across repos and do not use these scope settings.

For a repo, Mogplex resolves runnable connections by starting with enabled global connections, removing excluded globals, then adding enabled project connections.

Read Connection Scope and Overrides for the full operating model.

MCP limitsCopy Anchor Link

Mogplex caps enabled MCP server connections from Integrations at five per resolved scope. The MCP Servers catalog has no server-count cap.

The cap protects runs from receiving an oversized or noisy tool surface. If a repo reaches the cap, decide whether to:

• disable a connection
• exclude a global MCP from that repo
• move a repo-only tool to project scope
• replace overlapping MCPs with one better-scoped server

Do not add another broad MCP just because a tool call failed. First confirm the right server is in the resolved set for that repo.

CLI syncCopy Anchor Link

When the CLI is signed in with a Mogplex token, it can fetch your cloud MCP catalog from:

GET /api/v1/mogplex/mcp/servers

The CLI stores the fetched catalog in:

~/.mogplex/mcp-servers.remote.json

On startup, the CLI can use the remote list, the cache, or no cloud MCP list if there is no token and no cache. A network or auth failure can fall back to the cache so existing local work is not blocked by a transient catalog fetch issue.

Use /mcp in the CLI to inspect MCP state during a session.

Security notesCopy Anchor Link

• Treat MCP server config responses like .env files. They can include decrypted headers, env vars, or OAuth access tokens.
• Do not paste /api/v1/mogplex/mcp/servers output into issues, PRs, or chat logs.
• Prefer project-scoped connections when credentials only make sense for one repo.
• Exclude global MCPs from repos where the tool surface would be unsafe or distracting.
• Reconnect OAuth-backed presets from Connections when authorization expires.

TroubleshootingCopy Anchor Link

Read nextCopy Anchor Link