routeforge

[any MCP-aware agent]  --stdio-->  routeforge mcp   (skills, accounts, usage)
[curl / OpenAI client] --http-->  routeforge serve (OpenAI-compat + typed endpoints)
                                       |
                                       v
                              RoundRobinPool  --->  firecrawl / tavily / exa / ...
                              (cooldown on 429/402/5xx)

pip install -e ".[dev]"

# 1. Generate a master encryption key
export ROUTE_FORGE_MASTER_KEY=$(routeforge secrets generate)

# 2. Add one or more accounts per provider
routeforge accounts add --provider firecrawl --label personal-1 --key fc-xxx
routeforge accounts add --provider firecrawl --label personal-2 --key fc-yyy
routeforge accounts add --provider firecrawl --label personal-3 --key fc-zzz

# 3a. Run the HTTP server
routeforge serve
# -> http://127.0.0.1:8080

# 3b. Or run the MCP server over stdio (for Claude Code, Cursor, opencode, etc.)
routeforge mcp

# List registered skills
curl http://127.0.0.1:8080/v1/skills

# Call a skill directly
curl -X POST http://127.0.0.1:8080/skills/echo/call \
  -H 'Content-Type: application/json' \
  -d '{"args": {"hello": "world"}}'

# OpenAI-compatible call
curl -X POST http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"skill:echo","messages":[{"role":"user","content":"hi"}]}'

# Inspect accounts (no secrets leaked)
curl http://127.0.0.1:8080/v1/accounts

# Aggregated usage
curl 'http://127.0.0.1:8080/v1/usage?provider=firecrawl'

# src/routeforge/skills/builtin/myprovider.py
from typing import Any
import httpx
from ..base import Skill
from ...models import Account, SkillSchemaModel


class MyProviderSearchSkill(Skill):
    name = "myprovider/search"
    provider = "myprovider"
    description = "Call the myprovider search API."

    def schema(self) -> SkillSchemaModel:
        return SkillSchemaModel(
            inputs={"type": "object", "properties": {"q": {"type": "string"}}, "required": ["q"]},
            outputs={"type": "object"},
        )

    async def execute(self, account: Account, args: dict[str, Any], http: httpx.AsyncClient) -> dict[str, Any]:
        r = await http.post(
            "https://api.myprovider.com/search",
            json={"q": args["q"]},
            headers={"Authorization": f"Bearer {account.api_key}"},
        )
        r.raise_for_status()
        return r.json()

{
  "mcpServers": {
    "routeforge": {
      "command": "routeforge",
      "args": ["mcp"],
      "env": {
        "ROUTE_FORGE_MASTER_KEY": "<your-fernet-key>"
      }
    }
  }
}