MCP

MCP (Model Context Protocol) is an open standard for connecting AI assistants to external tools and data sources. Jean2 has native MCP support — connect any MCP-compatible server and its tools become available to the agent automatically.

Configuration

MCP servers are configured in .jean2/mcp.json in your workspace directory:

{
  "servers": {
    "server-name": {
      "type": "local",
      "command": ["npx", "-y", "@anthropic/mcp-server-filesystem", "/path/to/dir"],
      "env": { "SOME_VAR": "value" },
      "timeout": 30000,
      "enabled": true
    }
  }
}

Each server has a unique name (the key in servers). Set "enabled": false to disable a server without removing its config.

Local Servers

Local servers run as child processes using stdio transport. Jean2 spawns the command with:

• command (required): Array of command and arguments, e.g. ["npx", "-y", "@some/mcp-server"]
• env (optional): Additional environment variables passed to the process
• timeout (optional): Connection timeout in milliseconds (default: 30000)
• cwd is automatically set to the workspace directory

Example — filesystem server:

{
  "servers": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@anthropic/mcp-server-filesystem", "/home/user/projects"]
    }
  }
}

Example — SQLite server:

{
  "servers": {
    "database": {
      "type": "local",
      "command": ["uvx", "mcp-server-sqlite", "--db-path", "/home/user/data/app.db"]
    }
  }
}

Remote Servers

Remote servers connect over HTTP. Jean2 tries StreamableHTTP first, then falls back to SSE (Server-Sent Events) automatically.

{
  "servers": {
    "my-api": {
      "type": "remote",
      "url": "https://mcp.example.com/sse",
      "headers": { "Authorization": "Bearer <token>" },
      "timeout": 30000
    }
  }
}

• url (required): The server endpoint URL
• headers (optional): HTTP headers included in every request
• timeout (optional): Connection timeout in milliseconds (default: 30000)

OAuth Authentication

Remote servers that require OAuth are supported out of the box. Jean2 handles the full token lifecycle including refresh.

{
  "servers": {
    "github": {
      "type": "remote",
      "url": "https://mcp.github.com/sse",
      "oauth": {
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret"
      }
    }
  }
}

OAuth is enabled by default for remote servers. Set "oauth": false to disable it.

When a server requires authentication:

1. The server status becomes needs_auth
2. Jean2 starts an OAuth flow with a callback server at 127.0.0.1:19876/mcp/oauth/callback
3. Tokens are stored in ~/.jean2/mcp-auth.json (file permissions: 0o600)
4. Token refresh is handled automatically

You can optionally provide clientId and clientSecret in the config. If omitted, Jean2 will use dynamic client registration if the server supports it.

How It Works

When a workspace is opened:

1. Jean2 reads .jean2/mcp.json from the workspace directory
2. For each enabled server, it attempts to connect
3. Once connected, it calls listTools to discover available tools
4. MCP tools are converted to AI SDK format with the naming pattern {server_name}_{tool_name}
5. These tools are merged into the session's tool list — the LLM sees them alongside built-in tools

When the LLM calls an MCP tool, Jean2 routes the call to the correct MCP server via the established connection. No special configuration needed — it just works.

Server Status

Each MCP server has a status visible in the client:

Status	Meaning
connected	Server is connected and tools are available
disabled	Server is disabled ("enabled": false in config)
failed	Connection failed — check the server command or URL
needs_auth	Server requires OAuth authentication
needs_client_registration	OAuth dynamic registration failed

Workspace Scope

MCP configuration is per-workspace. Create .jean2/mcp.json in each workspace that needs MCP servers. An agent working in one workspace cannot see or use MCP connections from another workspace.

MCP connections are initialized when the workspace is opened and shut down when the workspace is closed.