Connect an MCP server
MCP lets Workrun use tools that already exist in your environment or on a hosted service. A connection adds a server to the MCP servers registry; it does not give every Agent access to every discovered tool. Test and start the server first, then select only the tools an Agent needs.
MCP tools can read data or perform side effects with the permissions of their server. Connect only servers you trust, use narrowly scoped credentials, and require approval for actions such as sending, writing, or deleting.
Choose a connection type
Section titled “Choose a connection type”| Choose this | When the server runs | What you provide |
|---|---|---|
| Local process (stdio) | On this computer | A command, one argument per line, and any environment variables |
| Remote endpoint (HTTP) | On a hosted service | A public Streamable HTTP URL and, if required, authentication |
Use Local process for a command-line MCP server that Workrun should start on this device. Use Remote endpoint only when the provider documents a Streamable HTTP MCP endpoint; a regular REST API URL or an older SSE endpoint will not connect.
Connect a local stdio server
Section titled “Connect a local stdio server”Before adding the server, run its command in a terminal once. This confirms the runtime is installed and makes its required arguments and environment variables clear. Do not paste a shell pipeline, redirection, or a whole command line into Command: Workrun runs the command directly.
-
Open MCP servers from the account menu and select Add server.
-
Give the connection a recognizable name and description, for example
GitHub MCPandSearch and manage GitHub repositories. -
Under Connection type, choose Local process (stdio).
-
Enter the executable in Command. Put each command argument on its own line in Arguments. For example, a command that you would run as
npx -y @example/mcp-serverbecomes:Field Value Command npxArguments -y@example/mcp-server -
Add each required environment variable on its own line as
KEY=value. Values are encrypted with this server configuration. Keep secrets out of arguments, workflow inputs, Agent instructions, and screenshots. -
Leave Enable this server on and select Test connection. Confirm both that it succeeds and that the discovered tool names are the ones you expect.
-
Select Save server. Back in the registry, select Start and wait for the status to become Online.
Connect a remote HTTP server
Section titled “Connect a remote HTTP server”-
Add a server, name it, and choose Remote endpoint (HTTP).
-
Enter the provider’s public Streamable HTTP endpoint URL. It must begin with
https://orhttp://; prefer HTTPS whenever the service supports it. -
Select the authentication method documented by the provider:
Method Use it when Next step No authentication The endpoint is intentionally public Test the connection. Bearer token The provider issued a static access token Paste the token, then test the connection. It is stored encrypted. OAuth The provider requires browser authorization Save the server first, then select Authorize in the registry and finish in the browser. -
For no authentication or Bearer token, select Test connection before saving. For OAuth, save first, complete authorization, then select Reconnect or Start.
-
Confirm the server is Online and the discovered tool count is plausible. An online server with zero tools is connected, but cannot help an Agent.
Give an Agent the right tools
Section titled “Give an Agent the right tools”- Open the workflow and select the target Agent.
- Under Tools, choose the specific tools discovered from the running MCP server. Connecting a server alone does not add its tools to an Agent.
- Set a Call limit and Tool timeout. Start with a small call limit such as
1for a lookup or a side-effecting action; increase it only when the task genuinely needs repeated calls. - Enable human confirmation for sends, writes, deletes, payments, or other consequential actions. A tool’s own description is not a substitute for a review step.
- Give the Agent an instruction that says when to use the tool and its boundary. Then run a minimal test input and inspect the tool arguments, result, and any approval event in the run panel.
For example:
When the user asks for the status of an issue, use get_issue with the issue ID.Use it only to retrieve information. Do not create, edit, close, or comment on an issue.Verify the complete setup
Section titled “Verify the complete setup”The connection is ready only when all four checks pass:
- Test connection lists the expected tools.
- The saved server is Online in the registry.
- The intended tool is selected on the intended Agent.
- A small workflow run shows valid arguments and the expected result or approval record.
If a tool is sensitive, test first with a read-only operation or a non-production target. Treat connection testing as a transport check, not proof that an Agent will select the correct tool or arguments.
Connection state and session recovery
Section titled “Connection state and session recovery”The server registry updates connection state through native events. For HTTP servers, Online reflects the last observed session state; it is not a continuous remote reachability probe. If a session closes, use Reconnect to restore it. Workrun can also recreate a closed HTTP session on demand when the server is needed again, without a background reconnect loop.
Stopping an HTTP server connection closes its local session; stopping a local stdio server terminates its process. Failed OAuth initialization clears the pending authorization state so you can correct the configuration and authorize again.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Check first |
|---|---|
| Test connection fails for a local server | Run the executable manually. Then verify the executable is on PATH, each argument occupies its own line, the working-directory assumptions are valid, and environment variable names are exact. |
| Test connection fails for a remote server | Confirm the URL is the provider’s Streamable HTTP MCP endpoint, not a website or REST API URL. Check network access, TLS, and the selected authentication method. |
| The server is online but has no tools | The server connected but did not advertise tools. Inspect its configuration and logs; a resource-only or prompt-only MCP server has no Agent tools to select. |
| The Agent cannot see a tool | Start or reconnect the server, then explicitly select that tool in the Agent’s Tools. Also check that the workflow is saved. |
| OAuth keeps requesting authorization | Save the server before authorizing. Complete the browser flow, return to the same Workrun profile, then reconnect the server. Reauthorize if the provider revoked or expired the grant. |
| The Agent calls a tool too often or times out | Lower the call limit, make the Agent instruction more specific, and verify the server’s expected response time. Do not solve a slow server by indefinitely increasing the timeout. |
For local tools you can build and control yourself, see Use Python Apps. For tool contracts, confirmations, and runtime behavior, see Apps, tools, and MCP.