Skip to main content
An external MCP Server tool lets an Athena agent call functions offered by your service over Streamable HTTP. This differs from Athena’s own workspace MCP endpoint, which lets an external assistant manage Athena; see Workspace settings.

​
Connect and discover

  1. Open Tools, create an MCP Server tool, and set its name and description.
  2. Enter the service’s MCP Server URL, including its MCP path. It must be reachable from hosted Athena; localhost on your laptop is not your laptop from Athena’s network.
  3. Select an existing credential when the service expects a key, bearer token, or custom headers. For OAuth, use Sign in, authorize the requested access at the service, and wait for Signed in. Use Sign in again if the credential needs reconnection.
  4. Save the tool and use Refresh to discover its functions. Check the function names, input descriptions, and any error.
  5. Optionally set Tools Filter to the comma-separated function names you want exposed. An empty filter exposes the discovered catalog. Select only the operations needed for this agent.
  6. Attach the MCP tool in each relevant conversation node, review any node-specific function selection, and describe when to use it in the node prompt.
  7. Save, test a harmless function with synthetic data, inspect its result, and publish the workflow when ready.
Saving a server URL does not prove discovery succeeded. POST /api/v1/tools/{tool_uuid}/mcp/refresh can return HTTP 200 while its error field reports failure. Check discovered_tools too. Failed or empty discovery preserves the previous cached catalog, so confirm the functions are from a successful refresh after changing permissions or servers.

​
Configure caller approval

Under Ask the caller before running, choose: Per-function choices include Always ask and Never ask. These controls apply to supported Athena voice calls. For a gated action, the agent explains the action and needs a clear yes before running it; a no or unclear answer does not authorize execution. Do not assume every transport has the same voice confirmation behavior. Test approval, refusal, and ambiguity separately against a harmless test action. Verify that refusal produces no external mutation, and inspect the tool activity rather than relying only on the agent saying it has completed an action.

​
Troubleshooting

If discovery fails, check URL, public reachability, authentication, the external account’s permissions, and sign-in state. If a function is missing, check both the server-wide filter and node selection. If its schema changed, refresh the catalog and re-test argument handling. OAuth authorization is service-specific; Athena does not grant access the signed-in account lacks.