Connect to Hosted Server

“I was told there would be no installation…”

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

Quick Connect

Claude Code

claude mcp add mcwaddams-hosted --transport http "https://mcwaddams.l.supported.systems/mcp"

MCP Settings JSON

{
  "mcpServers": {
    "mcwaddams": {
      "transport": {
        "type": "streamable-http",
        "url": "https://mcwaddams.l.supported.systems/mcp"
      }
    }
  }
}

Python SDK

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

No API Key Required

The hosted server is currently free and open. No authentication needed.

What’s Available

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

Document Extraction

Extract text, images, metadata from Word, Excel, PowerPoint

Legacy Support

Process .doc, .xls, .ppt files from the 90s

MCP Resources

Index documents and fetch chapters/sheets on demand

Smart Fallbacks

Multiple extraction methods with automatic fallback

Hosted vs Local

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

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.

Uploading Documents

The hosted server cannot access files on your local machine. Instead, you have two options:

Option 1: URL Reference

If your document is already hosted online:

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

Option 2: Base64 Upload

For local files, encode them as base64 and pass via file_content:

Python

import base64
from pathlib import Path

# Read and encode your document
doc_path = Path("my-report.docx")
file_content = base64.b64encode(doc_path.read_bytes()).decode("utf-8")

# Call the tool with file_content
result = await session.call_tool("extract_text", {
    "file_path": "my-report.docx",  # Used for extension detection
    "file_content": file_content
})

JavaScript

import { readFileSync } from 'fs';

// Read and encode your document
const docBuffer = readFileSync('my-report.docx');
const fileContent = docBuffer.toString('base64');

// Call the tool with file_content
const result = await session.callTool("extract_text", {
    file_path: "my-report.docx",  // Used for extension detection
    file_content: fileContent
});

Bash/curl

# Encode document to base64
FILE_CONTENT=$(base64 -w 0 my-report.docx)

# Call via HTTP (simplified example)
curl -X POST https://mcwaddams.l.supported.systems/mcp \
  -H "Content-Type: application/json" \
  -d "{
    \"method\": \"tools/call\",
    \"params\": {
      \"name\": \"extract_text\",
      \"arguments\": {
        \"file_path\": \"my-report.docx\",
        \"file_content\": \"$FILE_CONTENT\"
      }
    }
  }"

file_path Still Required

When using file_content, the file_path parameter is still required but only used for extension detection. The server uses the extension to determine the correct processing method.

All Tools Support Upload

Every tool that accepts file_path also accepts file_content:

• extract_text - Extract text with base64 upload
• extract_images - Extract images with base64 upload
• convert_to_markdown - Convert Word docs to Markdown
• analyze_excel_data - Analyze uploaded spreadsheets
• And all other document tools…

Self-Hosting

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

Docker Compose

services:
  mcwaddams:
    image: ghcr.io/ryanmalloy/mcwaddams:latest
    environment:
      - MCP_TRANSPORT=streamable-http
      - MCP_HOST=0.0.0.0
      - MCP_PORT=8000
      # Enable local file access (disabled by default for security)
      # - MCP_ALLOW_LOCAL_FILES=true
    ports:
      - "8000:8000"

Local File Access

By default, hosted servers only accept URLs and file_content uploads. If you’re self-hosting on a trusted network and want to access local files, set MCP_ALLOW_LOCAL_FILES=true.

With Caddy Reverse Proxy

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

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:

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

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.

---

“So if you could just go ahead and connect… that would be great.”