janusmcp

<div align="center">

# JanusMCP

**One credential broker. Every account. From the CLI or MCP.**
Multi-account tool access for AI agents, with credentials kept local.

[![CI](https://github.com/bayway/janusmcp/actions/workflows/ci.yml/badge.svg)](https://github.com/bayway/janusmcp/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/bayway/janusmcp?sort=semver)](https://github.com/bayway/janusmcp/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
![Status: alpha](https://img.shields.io/badge/status-alpha-orange)
[![Website](https://img.shields.io/badge/website-janusmcp.dev-7c8cff)](https://janusmcp.dev)

<br/>

[![Add to Cursor](https://img.shields.io/badge/Add_to-Cursor-0098FF?style=for-the-badge)](cursor://anysphere.cursor-deeplink/mcp/install?name=janusmcp&config=eyJjb21tYW5kIjogIm5weCIsICJhcmdzIjogWyIteSIsICJAYmF5d2F5L2phbnVzbWNwIiwgInNlcnZlIl19)
[![Install in VS Code](https://img.shields.io/badge/Install-VS_Code-007ACC?style=for-the-badge&logo=visualstudiocode)](https://insiders.vscode.dev/redirect/mcp/install?name=janusmcp&config=%7B%22command%22%3A%20%22npx%22%2C%20%22args%22%3A%20%5B%22-y%22%2C%20%22%40bayway/janusmcp%22%2C%20%22serve%22%5D%7D)

<sub>One-click buttons require the npm package to be published. See <a href="RELEASING.md">RELEASING.md</a>.</sub>

</div>

## The problem

If you work with more than one company, you use the *same* MCP server (Supabase, GitHub,
Slack…) with **different identities** — a different account, email and token per client.
Today most LLM clients hold **one account at a time** per connector: to switch client you
disconnect, reconnect, and redo the OAuth login. Every time.

The MCP protocol has no notion of "account": **one session = one identity = one set of
credentials.** JanusMCP fills that gap.

## What it does

JanusMCP is a **local multi-account tool broker** for AI agents. It can be used directly
from the CLI or as an MCP server in front of the real upstream servers:

- **Add N accounts once** for the same service and keep them all available.
- **Switch identity without reconnecting** — no re-login, no fiddling with config.
- **Works with any LLM client** — it just speaks standard MCP (stdio + Streamable HTTP).
- **Works without an MCP session too** — agents can drive it **directly from the CLI**
  ([code-execution mode](#code-execution-mode--context-efficient-tools-from-the-terminal)):
  `janusmcp tools` / `schema` / `call` invoke tools on demand, with no bulk tool
  definitions loaded upfront.
- **Runs locally** — your machine, your keychain, your control.
- **Keeps the context clean** — it exposes only the *active* account's tools, not N×tools.

```
                 ┌─────────────────────────────┐   ┌─ Supabase (Client A)
LLM client ─MCP─▶│   JanusMCP broker           │─▶ ├─ Supabase (Client B)
(Claude/GPT/     │   active-account · vault ·  │   ├─ GitHub  (Client A)
 Gemini/…)       │   per-session scoping       │   └─ …
                 └─────────────────────────────┘
```

You drive it with three control tools that appear in any client:
`janus_list_accounts`, `janus_use_account`, `janus_whoami`.

## Choose your mode

### Use from the CLI — Claude Code, Codex, Cursor, scripts

```bash
npm install -g @bayway/janusmcp
janusmcp tools
janusmcp schema list_tables
janusmcp call list_tables --args '{"schemas":["public"]}' --json --timeout 30s
```

The CLI discovers schemas only when needed, accepts JSON through `--args` or stdin,
supports explicit accounts/profiles, and provides stable exit codes. See the
[CLI guide](https://janusmcp.dev/cli/) and [copyable agent instructions](docs/agent-cli.md).

### Connect over MCP — desktop and chat clients

```bash
npx @bayway/janusmcp serve
# or configure a supported client automatically:
janusmcp install claude-desktop
```

Both modes share the same config, OS-keychain vault, OAuth tokens and persisted active
account. Use `janusmcp daemon start` to keep upstream sessions warm across repeated CLI calls.

## Install

Once released, install via your favorite channel (all published automatically on each
tag — see [RELEASING.md](RELEASING.md)):

```bash
npx @bayway/janusmcp serve                       # npm / MCP mode
brew install bayway/janusmcp/janusmcp     # Homebrew (macOS/Linux)
scoop install janusmcp                               # Windows
docker run --rm -p 7332:7332 ghcr.io/bayway/janusmcp:latest
```

…or download a prebuilt binary from [Releases](https://github.com/bayway/janusmcp/releases).

## Build from source (60-second quickstart)

```bash
git clone https://github.com/bayway/janusmcp
cd janusmcp/go
make build                       # produces ./bin/janusmcp
cp config.example.json config.json   # edit with your accounts
./bin/janusmcp serve             # stdio, for Claude Desktop/Code
```

Two Supabase clients, PATs kept in your OS keychain (never in the config):

```bash
./bin/janusmcp vault set supabase_client_a   # paste the PAT
./bin/janusmcp vault set supabase_client_b
```

```jsonc
// config.json
{
  "bindingMode": "session",
  "accounts": [
    { "id": "client_a", "service": "supabase", "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase@latest", "--read-only", "--project-ref=REF_A"],
      "env": { "SUPABASE_ACCESS_TOKEN": "vault:supabase_client_a" } },
    { "id": "client_b", "service": "supabase", "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase@latest", "--read-only", "--project-ref=REF_B"],
      "env": { "SUPABASE_ACCESS_TOKEN": "vault:supabase_client_b" } }
  ]
}
```

Add it to Claude Desktop:

```json
{ "mcpServers": { "janusmcp": {
  "command": "/abs/path/janusmcp/go/bin/janusmcp", "args": ["serve"],
  "env": { "JANUS_CONFIG": "/abs/path/janusmcp/go/config.json" } } } }
```

For ChatGPT / Gemini / Cursor / Copilot, run HTTP and point them at the URL:

```bash
JANUS_TRANSPORT=http JANUS_HTTP_PORT=7332 ./bin/janusmcp serve
# → http://127.0.0.1:7332/mcp
```

## Commands

Run `janusmcp help` for the full reference. The essentials:

| Command | What it does |
|---|---|
| `janusmcp serve` | Run the broker (default). Transports via env: `JANUS_TRANSPORT=stdio\|http\|both`, `JANUS_HTTP_HOST`, `JANUS_HTTP_PORT`. |
| `janusmcp tools [selector]` | Compact tool list for the active (or given) account/profile. `--json` for full definitions; optional `--timeout`. |
| `janusmcp schema <tool>` | Full JSON definition of one tool. `--account <id\|profile>` disambiguates; optional `--timeout`. |
| `janusmcp call <tool>` | Invoke a tool. Supports `--account`, `--args`, stdin, stable `--json`, and optional `--timeout`. |
| `janusmcp use <account\|profile>` | Persist the active selector for future CLI commands and new MCP sessions. |
| `janusmcp daemon start\|stop\|restart\|status` | Manage the optional loopback-only daemon that reuses upstream sessions. |
| `janusmcp ui` | Open the local control panel — add accounts, log in, set secrets. |
| `janusmcp add <template> [id]` | Add an account from a template (`janusmcp catalog` lists them). |
| `janusmcp catalog` | List the built-in account templates. |
| `janusmcp connect <id>` | Connect an account; for remote OAuth, opens the browser. |
| `janusmcp status` | Show each account's login/secret status (no secret values). |
| `janusmcp vault set <name>` / `delete <name>` | Store / remove a secret in the OS keychain. |
| `janusmcp login <provider> <name>` | OAuth loopback login; token referenced as `oauth:<name>`. |
| `janusmcp providers` | List built-in OAuth providers. |
| `janusmcp install <client>` | Configure an LLM client to launch JanusMCP. |
| `janusmcp uninstall <client>` | Remove JanusMCP from an LLM client's config. |
| `janusmcp version` · `janusmcp help` | Version · this reference. |

Supported `<client>` values for `install` / `uninstall`: `claude-desktop`, `claude-code`,
`cursor`, `vscode`, `gemini`, `codex`, `chatgpt`, `print`. Run `janusmcp install list`
(or `uninstall list`) to see each target and whether it's already configured.

```bash
janusmcp install claude-desktop      # one-command setup
janusmcp uninstall claude-desktop    # clean removal (restart the client afterwards)
```

Inside any connected client you also get the control tools `janus_list_accounts`,
`janus_use_account`, `janus_whoami`, `janus_login`, `janus_use_profile`, and
`janus_with_account`.

### Profiles — a whole client's stack at once

A **profile** groups accounts of the same client across different services. Activating
it exposes the tools of *all* its accounts together, and each call is routed to the
right upstream:

```jsonc
// config.json
{
  "accounts": [
    { "id": "supabase_a", "service": "supabase", "transport": "http", "url": "https://mcp.supabase.com/mcp", "auth": "oauth" },
    { "id": "github_a",   "service": "github",   "transport": "http", "url": "https://api.githubcopilot.com/mcp/", "auth": "oauth" }
  ],
  "profiles": {
    "client_a": ["supabase_a", "github_a"]
  }
}
```

Then in chat: `janus_use_profile` with `{ "profile": "client_a" }` → Supabase **and**
GitHub tools for Client A are available simultaneously. Colliding tool names across
accounts are namespaced (`<account>_<tool>`).

### One-shot cross-account calls

`janus_with_account` runs a single call on another account **without** changing the
active one — e.g. `{ "account_id": "client_b", "tool": "list_tables" }`. Omit `tool`
to list that account's available tools first.

### Code-execution mode — context-efficient tools from the terminal

Loading every MCP tool definition into an LLM context is expensive. In code-execution
mode an agent (or you) invokes tools **on demand from the shell** instead — à la
["code execution with MCP"](https://www.anthropic.com/engineering/code-execution-with-mcp) —
so the context holds only the results it actually asked for:

```bash
janusmcp tools                        # compact list for the active account/profile
janusmcp tools client_a               # ...or any account/profile expli