> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useagentflow.co/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Servers

> Connect remote Model Context Protocol servers and provision their tools

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.

```python theme={null}
catalog = await client.mcp_catalog.list()
installed = await client.mcp_catalog.install(catalog[0].catalog_id)
if installed.server is None:
    raise RuntimeError(installed.message)

discovery = await client.mcp_servers.discover(installed.server.id)
print([tool.remote_tool_name for tool in discovery.tools])
```

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](/sdk/mcp) and the [MCP API reference](/api-reference/mcp/list-mcp-catalog).