MCP Connector

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.

ℹ️

Note

An MCP Connector tool connects to an entire MCP server. You cannot select individual tools from a server.

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.

from seekrai import SeekrFlow
from seekrai.types import MCPConnector, MCPConnectorConfig

client = SeekrFlow()

mcp_connector_tool = client.tools.create(
    MCPConnector(
        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}")

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.

❗

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.

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:

mcp_connector_tool = client.tools.create(
    MCPConnector(
        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}")

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:

mcp_connector_tool = client.tools.create(
    MCPConnector(
        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}")

The tool is created with active status immediately.

Tool status

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

Link to an agent

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}")

Only active tools can be linked to an agent.

Manage your tool

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

from seekrai.types import UpdateMCPConnector

updated_tool = client.tools.update(
    mcp_connector_tool.id,
    UpdateMCPConnector(
        name="updated_name",
        description="Updated description."
    )
)

ℹ️

Changing the MCP server URL or credentials

The MCP server URL and authentication credentials cannot be updated on an existing tool. To use a different server or credentials, delete the tool and create a new one, then update your agent's tool_ids. MCP Connector tools cannot be duplicated.

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.

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.