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

# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# ~/.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}
```

<Note>
  `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](/docs/features/single-source-config) for the full schema.
</Note>

### With OAuth

<Warning>
  OAuth support is currently **experimental**. For production use, we recommend using `headers:` with API key authentication instead. See [OAuth Authentication](./mcp-oauth) for details.
</Warning>

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, MCP

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

### With Headers

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, MCP

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

### WebSocket Transport

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Not yet supported via CLI - use config file
```

### List Servers

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai mcp auth github
```

### Verify Connection

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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](../cli/mcp#verify-mcp-setup).

## Multiple Remote Servers

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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   |

## Related

* [OAuth Authentication](./mcp-oauth) - OAuth 2.1 for remote servers
* [MCP Server](../deploy/servers/praisonai-mcp) - Deploy your own MCP server
* [Local MCP](./mcp-local) - Local MCP servers via stdio