Integration Guide

Connect Odysseus to Admin Substitute

Run your own private AI workspace on your hardware. Connect it to 102 trade business tools via MCP. No cloud dependency. Full privacy. Your data never leaves your machine.

Odysseus on GitHub — MIT licensed, open-source, built by Felix Kjellberg.

Get Started Browse All 102 Tools

Why Odysseus + Admin Substitute

Odysseus is a self-hosted AI workspace with chat, agents, deep research, memory, and self-evolving skills — all running on your hardware. Admin Substitute is an MCP server with 102 tools across 29 domains purpose-built for Australian trade businesses.

Together, they create something no competitor offers: a private AI back-office that runs on your own machine, connected to real business tools. Your data stays on your hardware. Your agents connect to Admin Substitute via MCP to manage leads, quotes, jobs, invoices, compliance, and more.

Privacy-First

Your conversations, business data, and AI context never leave your machine.

Your Hardware

Run local models via Ollama, vLLM, or llama.cpp. Or use external APIs — your choice.

102 Trade Tools

Leads, quotes, jobs, invoicing, compliance, analytics — all accessible via MCP.

Prerequisites

1. Admin Substitute API Key

You need an API key to authenticate with the MCP server. Get one by:

2. Odysseus Installed

Docker (recommended) or native Python 3.11+. See the Odysseus README for install instructions.

MCP Configuration

Add Admin Substitute as an MCP server in your Odysseus settings. Go to Settings → MCP Servers and add a new server, or edit your config file directly:

Odysseus MCP config (Settings → MCP Servers)
Name:        Admin Substitute
URL:         https://adminsubstitute.com/api/v1/mcp/sse
Transport:   SSE
Auth Header: Authorization: Bearer YOUR_API_KEY

# Replace YOUR_API_KEY with your Admin Substitute API key
# The SSE endpoint supports Claude Desktop, Cursor, and Odysseus natively

Or if you prefer the JSON config format:

mcp_servers config block
{
  "admin-substitute": {
    "url": "https://adminsubstitute.com/api/v1/mcp/sse",
    "transport": "sse",
    "headers": {
      "Authorization": "Bearer ask_YOUR_API_KEY"
    },
    "description": "102 trade business tools across 29 domains"
  }
}

Streamable HTTP alternative: If your Odysseus version supports Streamable HTTP transport, use POST https://adminsubstitute.com/api/v1/mcp instead of the SSE endpoint.

Docker Setup

The fastest way to get Odysseus running with Admin Substitute connected:

Quick start (Docker)
# Clone Odysseus
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

# Copy the example env and add your Admin Substitute API key
cp .env.example .env

# Start Odysseus (includes ChromaDB, SearXNG, ntfy)
docker compose up -d

# Open http://localhost:7000 in your browser
# Go to Settings → MCP Servers → Add:
#   Name: Admin Substitute
#   URL:  https://adminsubstitute.com/api/v1/mcp/sse
#   Auth: Bearer YOUR_API_KEY

Native Setup (macOS / Linux)

Native install
# Clone and set up
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# macOS with Apple Silicon (Metal GPU acceleration)
./start-macos.sh

# Linux / Windows
python -m uvicorn app:app --host 127.0.0.1 --port 7000

# Then add the MCP server in Settings as above

Verify Connection

Once configured, test the connection by asking your Odysseus agent to list available tools:

Test in Odysseus chat
You: "List all available Admin Substitute tools"

Agent: Found 102 tools across 29 domains:
  • leads.list — List all leads with filters
  • quotes.create — Generate a new quote
  • jobs.list — View scheduled and active jobs
  • analytics.summary — Get business performance metrics
  • workflows.daily_summary — Generate end-of-day AI summary
  ... and 97 more

You: "How many leads do I have this week?"

Agent: [Calling leads.list with filters...]
  You have 12 new leads this week:
  • 4 plumbing enquiries (2 qualified)
  • 3 electrical requests
  • 5 general maintenance
  Recommended: Follow up on the 2 qualified plumbing leads first.

Use Cases for Tradies

Here's what becomes possible when your private AI workspace connects to real trade business tools:

Competitor Research

"Research my top 5 competitors in Penrith for plumbing. Get their Google reviews, pricing, and services."

leads.listanalytics.summaryformation.demand_hotspots

Multi-source competitive analysis with citations, pricing comparisons, and gap opportunities.

Autonomous Quoting

"Generate a quote for a bathroom renovation at 42 Smith St, Parramatta. Hot water, tiling, plumbing rough-in."

quotes.createquotes.ai_price_suggestionpricebook.search

AI-priced quote pulled from your price book, sent to the client, logged in your CRM.

Morning Business Brief

"Give me a morning brief: yesterday's revenue, overdue invoices, today's schedule, and any leads I haven't followed up."

analytics.summaryworkflows.chase_paymentjobs.listleads.list

Full business snapshot with actionable next steps, delivered through your private AI workspace.

Lead Pipeline Automation

"Process all new leads from today. Send quotes to qualified ones, follow up stale leads, and update the pipeline."

workflows.process_leadworkflows.instant_responseworkflows.follow_up_quote

Autonomous pipeline management — leads scored, quotes sent, follow-ups triggered, all from your own hardware.

Deep Research Pipeline

Odysseus includes a multi-step Deep Research engine (adapted from Tongyi DeepResearch). Combined with Admin Substitute's business data, your agent can run autonomous research missions:

Market Intelligence

Research competitor pricing, market gaps, and demand hotspots in your area

Compliance Research

Look up licensing requirements, insurance obligations, and WHS regulations for any state

Supplier Analysis

Compare supplier pricing across your trade using 930+ catalogue items

Growth Opportunities

Identify underserved suburbs, high-demand trades, and government funding you qualify for

Example: Deep Research + MCP tools
You: "Deep research: What's the average hourly rate for
      electricians in Western Sydney? Compare with my current
      pricing and suggest adjustments."

Odysseus Deep Research Pipeline:
  1. Decompose → 3 sub-queries
  2. Web search → 8 sources found (hipages, Airtasker, ABS)
  3. Rank sources → 5 high-relevance
  4. Synthesise → Cited report

Then calls MCP tools:
  → analytics.summary (your current pricing data)
  → formation.demand_hotspots (Western Sydney demand)
  → pricebook.search (material cost benchmarks)

Final Report:
  "Western Sydney electricians charge $85-120/hr (median $95).
   Your current rate of $80/hr is 16% below market.
   Recommendation: Increase to $95/hr for new quotes.
   Supporting data: [5 cited sources]"

Troubleshooting

Connection refused or timeout

Ensure Odysseus can reach the internet. If running in Docker, check your network configuration. The MCP endpoint requires outbound HTTPS access to adminsubstitute.com.

Authentication error (-32603)

Your API key may be invalid or expired. Check that you're using the full key including the ask_ prefix. Generate a new key from your Admin Substitute dashboard if needed.

Tool not found

Some tools require specific plan tiers. Free/public tools (formation.*, lifecycle.*) work without a paid plan. Business tools (leads.*, quotes.*, jobs.*) require Starter+ plans.

SSE connection drops

SSE connections have a keepalive ping every 30 seconds. If your proxy or firewall kills idle connections, switch to the Streamable HTTP transport (POST /api/v1/mcp) instead.

Your hardware. Your data. 102 trade tools.

The only trade management platform that works with self-hosted AI. Connect Odysseus and start running your business from your own machine.