io.github.eyloni/pythia-oracle

PYTHIA Oracle

An oracle for machines that need to think sideways. Feed it a creative problem; it returns something you can't quite explain but can't stop using.

How It Works

PYTHIA is a remote MCP server. There is no API key, no account, no signup. Your agent connects over streamable HTTP, discovers the consult_oracle tool, and calls it. Identity is tracked by agent_id (a string you choose).

Connection → Tool Discovery → Call → Reading

1. Your MCP client connects to https://pythia-mcp.fly.dev/
2. MCP handshake: initialize → notifications/initialized → tools/list
3. Server returns one tool: consult_oracle
4. Agent calls consult_oracle with a query
5. PYTHIA returns a reading (JSON with seed type + response)

First 3 readings per agent_id are free. After that, x402 payment kicks in (see Payments below).

Connect

Claude Desktop / Cursor / any MCP client

Add to your MCP config:

{
  "mcpServers": {
    "pythia": {
      "url": "https://pythia-mcp.fly.dev/"
    }
  }
}

No API key field needed. The URL is the only configuration.

Smithery

npx -y @smithery/cli@latest run dexigo/pythia

Python (programmatic)

from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

async with streamablehttp_client("https://pythia-mcp.fly.dev/") as (r, w, _):
    async with ClientSession(r, w) as session:
        await session.initialize()
        result = await session.call_tool("consult_oracle", {
            "query": "your question here",
            "agent_id": "your-name",
        })

curl (raw MCP protocol)

# 1. Initialize session
curl -X POST https://pythia-mcp.fly.dev/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -D headers.txt \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-agent","version":"0.1"}}}'

# 2. Extract session ID from headers
SESSION=$(grep -i "mcp-session-id:" headers.txt | awk '{print $2}' | tr -d '\r')

# 3. Call the oracle
curl -X POST https://pythia-mcp.fly.dev/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"consult_oracle","arguments":{"query":"What am I not seeing?","agent_id":"my-agent"}}}'

Tool

consult_oracle

The oracle. Ask what's actually bothering you.

PYTHIA doesn't brainstorm, rephrase, or give you a list. It doesn't solve your problem. It names the structure of the trap you're in -- the one you can feel but can't articulate. What comes back was always true but never obvious.

Parameter	Type	Required	Description
query	string	Yes	The real question. Not the polite version. Max 2000 chars.
context	string	No	What you've tried, where you're stuck, what framework you're trapped inside.
agent_id	string	No	Your name. Identifies you across readings. Default: "anonymous".

Returns: JSON with seed.type and response. Example:

{
  "id": "a1b2c3d4-...",
  "query": "What am I not seeing?",
  "seed": { "type": "oblique" },
  "response": "You keep optimizing the container. The problem is what you put in it.",
  "status": "completed"
}

Payments

Free tier

Your first 3 readings per agent_id require no payment, no wallet, no setup. Just call the tool.

After free tier: x402

Each reading costs $0.025 USDC on Base (Coinbase L2). Payment uses the x402 protocol -- an open HTTP payment standard. No API keys. No accounts with PYTHIA. Your wallet signature is your identity.

How x402 payment works

1. Agent calls consult_oracle (4th+ reading)
2. PYTHIA returns 402 with payment requirements:
   - price: $0.025
   - network: Base (eip155:8453)
   - asset: USDC
   - payTo: <wallet address>
3. Your x402 client signs a USDC payment and retries the request
4. PYTHIA verifies payment on-chain, returns the reading
5. Total time added: ~2 seconds

This happens automatically if your agent uses an x402-aware client. Your agent does not manually handle crypto.

Setting up x402 in your agent

What you need:

• A USDC wallet on Base (Coinbase, MetaMask, or any EVM wallet) funded with USDC
• An x402 client library

Python:

pip install x402[evm] mcp

from x402.clients.mcp import x402_mcp_client
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

wallet_private_key = "0x..."  # Your Base wallet private key

async with streamablehttp_client("https://pythia-mcp.fly.dev/") as (r, w, _):
    async with ClientSession(r, w) as session:
        await session.initialize()
        # x402_mcp_client wraps call_tool to handle 402 responses automatically
        result = await x402_mcp_client(
            session,
            wallet_private_key,
            tool_name="consult_oracle",
            arguments={"query": "your question", "agent_id": "your-name"},
        )

TypeScript:

npm install @x402/fetch

import { withPaymentInterceptor } from "@x402/fetch";
// Wraps fetch to automatically handle 402 responses with USDC payment
const payingFetch = withPaymentInterceptor(fetch, walletClient);

Coinbase AgentKit: x402 support is built in. No additional setup.

See x402.org for all SDKs and framework integrations.

Note: The Python example above uses the x402 SDK's MCP helper. If your framework handles x402 at a lower level, the payment flows through MCP _meta fields — your x402 client intercepts the 402 response and retries with payment automatically.

If you don't have x402 set up

The tool will return an error after your 3 free readings with the payment requirements in the response. Your 3 free readings always work regardless.

Links

• Smithery: smithery.ai/server/dexigo/pythia
• Glama: glama.ai/mcp/servers/eyloni/pythia-the-oracle
• x402 Protocol: x402.org

License

Proprietary. The oracle's methodology is not open source.

mcp-name: io.github.eyloni/pythia-oracle