mcwaddams-site/src/content/docs/how-to/hosted-mcp.mdx

---
title: Connect to Hosted Server
description: Use mcwaddams without installing anything locally.
---

import { Aside, Code, Tabs, TabItem, Card, CardGrid } from '@astrojs/starlight/components';

> *"I was told there would be no installation..."*

Don't want to install anything? Connect to our hosted mcwaddams server via HTTP.

## Quick Connect

<Tabs>
  <TabItem label="Claude Code">
    ```bash
    claude mcp add mcwaddams-hosted --transport http "https://mcwaddams.l.supported.systems/mcp"
    ```
  </TabItem>
  <TabItem label="MCP Settings JSON">
    ```json
    {
      "mcpServers": {
        "mcwaddams": {
          "transport": {
            "type": "streamable-http",
            "url": "https://mcwaddams.l.supported.systems/mcp"
          }
        }
      }
    }
    ```
  </TabItem>
  <TabItem label="Python SDK">
    ```python
    from mcp import ClientSession
    from mcp.client.streamable_http import streamable_http_client

    async with streamable_http_client("https://mcwaddams.l.supported.systems/mcp") as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print(f"Connected! {len(tools.tools)} tools available")
    ```
  </TabItem>
</Tabs>

<Aside type="tip" title="No API Key Required">
The hosted server is currently free and open. No authentication needed.
</Aside>

## What's Available

All 20+ mcwaddams tools are available via the hosted server:

<CardGrid>
  <Card title="Document Extraction" icon="document">
    Extract text, images, metadata from Word, Excel, PowerPoint
  </Card>
  <Card title="Legacy Support" icon="puzzle">
    Process `.doc`, `.xls`, `.ppt` files from the 90s
  </Card>
  <Card title="MCP Resources" icon="list-format">
    Index documents and fetch chapters/sheets on demand
  </Card>
  <Card title="Smart Fallbacks" icon="rocket">
    Multiple extraction methods with automatic fallback
  </Card>
</CardGrid>

## Hosted vs Local

| Feature | Hosted | Local (uvx) |
|---------|--------|-------------|
| Installation | None | `uvx mcwaddams` |
| File Access | URL only | Local + URL |
| Speed | Network latency | Instant |
| Privacy | Files processed on server | Files stay local |
| Availability | Requires internet | Works offline |

<Aside type="caution" title="Privacy Note">
When using the hosted server, your documents are transmitted to and processed on our server. For sensitive documents, use the local installation instead.
</Aside>

## Using with URLs

The hosted server can process documents from URLs directly:

```python
# Extract text from a public document
result = await session.call_tool("extract_text", {
    "file_path": "https://example.com/report.docx"
})
```

This is particularly useful for processing documents already hosted online.

## Self-Hosting

Want the convenience of HTTP without using our server? Self-host your own:

### Docker Compose

```yaml
services:
  mcwaddams:
    image: ghcr.io/ryanmalloy/mcwaddams:latest
    environment:
      - MCP_TRANSPORT=streamable-http
      - MCP_HOST=0.0.0.0
      - MCP_PORT=8000
    ports:
      - "8000:8000"
```

### With Caddy Reverse Proxy

Clone the repo and use our docker-compose with caddy-docker-proxy labels:

```bash
git clone https://github.com/ryanmalloy/mcwaddams.git
cd mcwaddams
cp .env.example .env
# Edit .env to set your hostname
make docker-up
```

Your server will be available at `https://your-domain.com/mcp`

### Local Development

Run HTTP mode locally without Docker:

```bash
# Install
pip install mcwaddams

# Run with HTTP transport
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 python -m mcwaddams.server
```

Or with uv:

```bash
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx mcwaddams
```

## Troubleshooting

### Connection Refused

```
Error: Connection refused
```

The server may be temporarily down. Try:
1. Check server status at https://status.supported.systems
2. Fall back to local installation: `uvx mcwaddams`

### Timeout Errors

Large documents may take longer to process. The hosted server has a 60-second timeout per request.

For very large documents, consider:
- Using local installation
- Processing documents in chunks via pagination

### SSL/TLS Errors

Ensure you're using `https://` not `http://`. The hosted server requires TLS.

---

<div style="text-align: center; margin-top: 2rem; font-style: italic; opacity: 0.7;">
*"So if you could just go ahead and connect... that would be great."*
</div>