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

# MCP connector

> Connect a remote MCP server to your agent so it can invoke external tools without a custom integration.

With the MCP connector tool, agents can call tools hosted on external Model Context Protocol (MCP) servers. SeekrFlow handles authentication, token refresh, and outbound requests.

## When to use

Use an MCP connector tool when you want to connect an agent to an external MCP server.

## Prerequisites

* An MCP server URL
* For OAuth servers without dynamic client registration: a `client_id` and `client_secret` from the provider

## Create an MCP connector tool

SeekrFlow supports three authentication modes depending on your MCP server.

<Info>
  An MCP connector tool connects to an entire MCP server. You cannot select individual tools from a server.
</Info>

### Servers with dynamic client registration (DCR)

If the MCP server supports DCR, provide the server URL. SeekrFlow registers itself as an OAuth client and initiates the authorization flow.

<CodeGroup>
  ```python Python theme={null}
  from seekrai import SeekrFlow
  from seekrai.types import CreateMCPConnector, MCPConnectorConfig

  client = SeekrFlow()

  mcp_connector_tool = client.tools.create(
      CreateMCPConnector(
          name="my_mcp_tool",
          description="Access external data and actions via the Example MCP server.",
          config=MCPConnectorConfig(
              url="https://mcp.example.com"
          )
      )
  )
  print(f"Tool ID: {mcp_connector_tool.id}")
  print(f"Status: {mcp_connector_tool.status}")
  print(f"Authorization URL: {mcp_connector_tool.config.AUTHORIZATION_URL}")
  ```
</CodeGroup>

The tool is created with a status of `pending_authorization`. Open the `AUTHORIZATION_URL` from the response in a browser and complete the OAuth flow. Once authorized, the tool status changes to `active` and it can be linked to an agent.

<Danger>
  **Authorization window**

  You must complete the OAuth flow within one hour. If the window expires, the tool moves to `failed` status and cannot be recovered. Delete it and create a new one.
</Danger>

### Servers without dynamic client registration

If your MCP server requires OAuth but does not support DCR, you'll need to register SeekrFlow as an OAuth client with the provider first. Use the SeekrFlow redirect URI provided in your account settings when configuring the OAuth client.

Once you have a `client_id` and `client_secret` from the provider:

<CodeGroup>
  ```python Python theme={null}
  mcp_connector_tool = client.tools.create(
      CreateMCPConnector(
          name="my_mcp_tool",
          description="Access external data and actions via the Example MCP server.",
          config=MCPConnectorConfig(
              url="https://mcp.example.com",
              client_id="your-client-id",
              client_secret="your-client-secret"
          )
      )
  )
  print(f"Status: {mcp_connector_tool.status}")
  print(f"Authorization URL: {mcp_connector_tool.config.AUTHORIZATION_URL}")
  ```
</CodeGroup>

Open the `AUTHORIZATION_URL` and complete the OAuth flow. The tool becomes `active` once authorized.

### Servers with no authentication

For MCP servers that require no authentication, provide only the URL:

<CodeGroup>
  ```python Python theme={null}
  mcp_connector_tool = client.tools.create(
      CreateMCPConnector(
          name="my_mcp_tool",
          description="Access the Example MCP server.",
          config=MCPConnectorConfig(
              url="https://mcp.example.com"
          )
      )
  )
  print(f"Tool ID: {mcp_connector_tool.id}")
  print(f"Status: {mcp_connector_tool.status}")
  ```
</CodeGroup>

The tool is created with `active` status immediately.

## Tool status

| Status                  | Description                                                                                                 | Can link to agent? |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------ |
| `pending_authorization` | OAuth flow not yet completed. Expires after one hour.                                                       | No                 |
| `active`                | Authentication complete. Tool is ready to use.                                                              | Yes                |
| `failed`                | Authorization timed out, or the tool failed at runtime (expired token, unreachable server, revoked access). | No                 |

If a tool enters `failed` status, delete it and create a new one.

## Link to an agent

<CodeGroup>
  ```python Python theme={null}
  from seekrai.types import CreateAgentRequest

  agent = client.agents.create(
      CreateAgentRequest(
          name="MyAgent",
          instructions="You are an expert assistant. Use the MCP tool to access external data when needed.",
          model_id="meta-llama/Llama-3.3-70B-Instruct",
          tool_ids=[mcp_connector_tool.id]
      )
  )
  print(f"Agent ID: {agent.id}")
  ```
</CodeGroup>

Only `active` tools can be linked to an agent.

## Manage your tool

You can update a tool's name and description at any time:

<CodeGroup>
  ```python Python theme={null}
  from seekrai.types import UpdateMCPConnector

  updated_tool = client.tools.update(
      mcp_connector_tool.id,
      UpdateMCPConnector(
          name="updated_name",
          description="Updated description."
      )
  )
  ```
</CodeGroup>

<Note>
  **Changing the MCP server URL or credentials**

  MCP connector tools cannot be duplicated. If you need to connect to a different server or change credentials, create a new MCP connector tool and update your agent's `tool_ids`.
</Note>

## Best practices

### Tool description

Write a description that tells the agent specifically when to invoke this tool and what kind of data or actions it provides.

| Effective                                                                                                                                                                           | Ineffective                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| "Use this tool to query live inventory data from the warehouse management system. Invoke it when the user asks about stock levels, item availability, or order fulfillment status." | "Use this tool to access the MCP server." |

### Handle tool failures

If a tool moves to `failed` during production use (for example, due to a provider token expiry), the agent will still call it, the call will fail, and the run will continue. To avoid unexpected failures, monitor tool status regularly and recreate tools before they impact your agent.