Remote MCP Servers

Connect agents to remote MCP servers for cloud-hosted tools and services.

Quick Start

from praisonaiagents import Agent, MCP

# Connect to remote MCP server
agent = Agent(
    instructions="You help with web research",
    tools=MCP("https://mcp.tavily.com/mcp")
)

agent.start("Search for AI news")

Transport Types

PraisonAI automatically detects the transport type from the URL:

URL Pattern	Transport	Description
`http://` or `https://`	HTTP Stream	Streamable HTTP (MCP 2025-11-25)
`http://.../sse`	SSE	Server-Sent Events (legacy)
`ws://` or `wss://`	WebSocket	Bidirectional WebSocket

Configuration

Remote Server in Config

Declared servers in ~/.praisonai/config.yaml (global) or ./.praisonai/config.yaml (project) are now wired into praisonai run automatically.

# ~/.praisonai/config.yaml  (or .praisonai/config.yaml for project-scoped)
mcp:
  servers:
    tavily:
      type: remote
      url: https://mcp.tavily.com/mcp
      enabled: true
      timeout: 30000
      headers:
        Authorization: Bearer ${TAVILY_API_KEY}

type: remote servers are served through the Python SDK’s MCP client and are not passed via the praisonai run command-string path. Local (stdio) servers use the command key instead. See Single-Source Config for the full schema.

With OAuth

OAuth-protected servers are now zero-config — just declare type: remote and url. On the first request, PraisonAI discovers the endpoints, registers a client, and opens your browser once to approve. See OAuth Authentication for the full flow.

mcp:
  servers:
    github:
      type: remote
      url: https://api.githubcopilot.com/mcp/

Supply an explicit oauth: block only as a fallback for servers that don’t advertise standard metadata or dynamic client registration:

mcp:
  servers:
    github:
      type: remote
      url: https://api.github.com/mcp
      oauth:
        client_id: your_client_id
        scopes:
          - repo
          - user

Python SDK

HTTP Stream Transport

from praisonaiagents import Agent, MCP

# Automatic HTTP Stream detection
agent = Agent(
    instructions="Research assistant",
    tools=MCP("https://mcp.example.com/mcp")
)

With Headers

from praisonaiagents import Agent, MCP

# API key authentication
agent = Agent(
    instructions="Research assistant",
    tools=MCP(
        "https://mcp.tavily.com/mcp",
        headers={"Authorization": "Bearer your-api-key"}
    )
)

SSE Transport (Legacy)

from praisonaiagents import Agent, MCP

# SSE endpoint (legacy)
agent = Agent(
    instructions="Weather assistant",
    tools=MCP("http://localhost:8080/sse")
)

WebSocket Transport

from praisonaiagents import Agent, MCP

# WebSocket connection
agent = Agent(
    instructions="Real-time assistant",
    tools=MCP("wss://mcp.example.com/ws")
)

CLI Commands

Add Remote Server

# Not yet supported via CLI - use config file

List Servers

praisonai mcp list

Output:

MCP Servers
┏━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Name     ┃ Type   ┃ Target                         ┃ Enabled ┃
┡━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ tavily   │ remote │ https://mcp.tavily.com/mcp     │ ✓       │
│ github   │ remote │ https://api.github.com/mcp     │ ✓       │
│ local-fs │ local  │ npx @anthropic-ai/mcp-server...│ ✓       │
└──────────┴────────┴────────────────────────────────┴─────────┘

Authenticate (OAuth)

praisonai mcp auth github

Runs the full OAuth 2.1 flow (PKCE + code exchange) and caches a real bearer token at ~/.praisonai/mcp-auth.json. See OAuth Authentication for the full flow.

Verify Connection

# Check MCP server health and configuration
praisonai mcp doctor

# List tools available from configured servers
praisonai mcp list-tools

For more CLI commands, see MCP CLI documentation.

Multiple Remote Servers

from praisonaiagents import Agent, MCP

# Combine multiple remote servers
agent = Agent(
    instructions="Multi-tool assistant",
    tools=[
        MCP("https://mcp.tavily.com/mcp"),
        MCP("https://api.github.com/mcp"),
        MCP("wss://realtime.example.com/ws")
    ]
)

Error Handling

from praisonaiagents import Agent, MCP

try:
    mcp = MCP("https://mcp.example.com/mcp", timeout=30)
    tools = mcp.get_tools()
    print(f"Connected! Found {len(tools)} tools")
except ConnectionError as e:
    print(f"Failed to connect: {e}")
except TimeoutError as e:
    print(f"Connection timed out: {e}")

Troubleshooting

Issue	Solution
Connection refused	Check URL and server status
401 Unauthorized	Add API key or authenticate with OAuth
Timeout	Increase timeout parameter
No tools found	Check server is running and has tools
SSL error	Use `https://` or check certificates

OAuth Authentication - OAuth 2.1 for remote servers
MCP Server - Deploy your own MCP server
Local MCP - Local MCP servers via stdio

​Quick Start

​Transport Types

​Configuration

​Remote Server in Config

​With OAuth

​Python SDK

​HTTP Stream Transport

​With Headers

​SSE Transport (Legacy)

​WebSocket Transport

​CLI Commands

​Add Remote Server

​List Servers

​Authenticate (OAuth)

​Verify Connection

​Multiple Remote Servers

​Error Handling

​Troubleshooting

​Related

Quick Start

Transport Types

Configuration

Remote Server in Config

With OAuth

Python SDK

HTTP Stream Transport

With Headers

SSE Transport (Legacy)

WebSocket Transport

CLI Commands

Add Remote Server

List Servers

Authenticate (OAuth)

Verify Connection

Multiple Remote Servers

Error Handling

Troubleshooting

Related