Praison AI

Remote MCP Servers

Connect to remote MCP servers via HTTP, SSE, or WebSocket

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

Quick Start

python
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 PatternTransportDescription
http:// or https://HTTP StreamStreamable HTTP (MCP 2025-11-25)
http://.../sseSSEServer-Sent Events (legacy)
ws:// or wss://WebSocketBidirectional 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.

yaml
# ~/.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}

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.

yaml
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:

yaml
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

python
from praisonaiagents import Agent, MCP

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

With Headers

python
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)

python
from praisonaiagents import Agent, MCP

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

WebSocket Transport

python
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

bash
# Not yet supported via CLI - use config file

List Servers

bash
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)

bash
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

bash
# 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

python
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

python
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

IssueSolution
Connection refusedCheck URL and server status
401 UnauthorizedAdd API key or authenticate with OAuth
TimeoutIncrease timeout parameter
No tools foundCheck server is running and has tools
SSL errorUse https:// or check certificates

Related