Skip to main content
AgentFlow can connect a tenant to remote Model Context Protocol (MCP) servers. A server definition records the endpoint and credential policy. Once an active credential is available, discovery reads the remote catalog, creates newly discovered tools with source="mcp_server", and provisionally assigns those new tools to MainAgent.

​
Lifecycle

  1. Install a curated server from client.mcp_catalog, or create a server definition with client.mcp_servers.create(...).
  2. Store a tenant- or user-scoped credential, or complete the server’s OAuth flow.
  3. Test the connection and discover remote tools.
  4. Review the newly provisioned tools on MainAgent, then change assignments, catalog status, and approval policy as needed.
Catalog installation creates or updates the server definition; the credential is normally the next required step. Credential activation and manual discovery both provision only tools that are new to AgentFlow. Existing administrator enablement and assignment decisions survive reconnects. import_tool(...) remains an explicit one-tool recovery path when automatic provisioning did not create a remote definition. It returns an unassigned tool; assign it through the agent tool APIs. Do not call it routinely after successful discovery because the tool may already exist.

​
Credential scopes

Each server declares its allowed credential scopes and one default. Tenant-scoped credentials are shared by authorized tenant workloads. User-scoped credentials belong to the authenticated user; credentials_self(...) returns only that caller’s credential metadata. API responses never return stored secret values. Set background_safe only when a credential may be used after the initiating request is no longer active. OAuth state is single-use and must be returned unchanged to the exchange endpoint.

​
Deletion behavior

Deleting a server also permanently deletes its imported tool definitions, removes their agent assignments, and deletes stored credentials. The response reports how many imported tools were removed. Treat server deletion as a destructive tenant-admin operation. See SDK: MCP and the MCP API reference.