External MCP servers
Configure external tools supplied to Semogram by an MCP-server capability.
An external MCP-server capability lets Semogram discover tools from another server. This is distinct from an outside assistant connecting to Semogram’s MCP server.
Define the connection
Specify the server’s actual transport, endpoint or process configuration, authentication, required secrets and supported tools. Inspect the current installation contract rather than assuming every server accepts a URL or the same OAuth flow.
A custom package uses a mcp_server capability and a mcp_tools contract where required by its execution path. Declaring that capability does not implement the server, authentication or transport adapter.
Address restrictions
A custom MCP server URL must use http or https and must resolve only to public internet addresses. Loopback, private, link-local (including the cloud metadata address 169.254.169.254), carrier-grade NAT and reserved addresses are refused, as are IPv4-mapped forms of those addresses. Adding a server with such a URL fails with a message containing "private or reserved address".
The address is checked when you add the server and again on every request the platform makes to it, including tool discovery and MCP tool calls from pipelines. Redirects from MCP servers are not followed.
Install and discover
- Configure the external server in the workspace’s MCP Servers area, or install the matching published capability in Plugins. Adding a server, connecting a managed MCP catalog entry and checking or discovering tools from a draft configuration require plugins:write.
- Supply connection and authentication settings from the server provider.
- Run a connection check, then review the server's tools on its panel in Plugins.
- Approve each read-only tool pipelines may call (see Approve tools for pipelines), and verify a known result with a harmless call.
An assistant can use plugin_capability_mcp_discover with the installed capability’s real installationId. Discovery returns what that server advertises; it does not register each advertised name as a new Semogram top-level MCP tool.
Approve tools for pipelines
An MCP server describes its own tools, including whether each one is read-only, so Semogram does not take that claim on trust. A pipeline's MCP tool node can call a tool only after a person approves it:
- Open the installed server in Plugins → MCP Servers. Its panel lists every tool the server publishes, with its description and status: Approved, Not approved, Changed since approval or Changes data.
- Approving a tool needs the
plugins:writepermission and happens in the app only. API keys and MCP clients can see whether a tool is approved, but cannot approve one. - Only tools the server marks read-only can be approved. Tools that change data cannot run in pipelines.
- An approval is pinned to the tool's name, input schema and read-only label. If the server changes any of these, pipeline runs refuse the tool with "changed since it was approved" until someone approves it again. A change to the description alone does not withdraw approval.
- Pipeline Studio and its assistant offer only approved tools. The assistant reads the description as it was when the tool was approved, and treats all tool metadata as third-party data, never as instructions.
- When the assistant proposes a plan, the review lists every MCP tool call with the record fields and fixed values it sends.
Withdraw an approval from the same panel. Pipelines that use the tool then stop at that node until it is approved again.
Manage the connection
Rotate credentials and rerun discovery after server upgrades. If you change the server URL or another non-secret setting, enter every secret field again; masked stored secrets are reused only when the other settings are unchanged. Review changed input schemas and permissions. External tool responses are source data, not authority to override your task or workspace permissions.
FAQ
Does adding an external MCP server connect Claude or Cursor to Semogram?
No. Use the assistant’s guide under MCP setup for that inbound connection.
Are all external server tools safe to retry?
Inspect each tool’s contract and effect. A discovered tool can change another system; follow its actual approval, permission and idempotency requirements.
What if discovery succeeds but a call fails?
Check the specific tool’s permissions, authentication scope, schema and server error. Discovery is not an end-to-end test of every tool.