@interviewlm/mcp

stdio MCP shim for InterviewLM — bridges stdio-only MCP clients (Codex, GitHub Copilot, Claude Desktop) to the InterviewLM remote MCP server via OAuth 2.1 + PKCE.

What it does

On first run it:

1. Discovers the InterviewLM Authorization Server metadata.
2. Registers a public PKCE client via Dynamic Client Registration (RFC 7591).
3. Opens your browser to the InterviewLM consent screen.
4. Receives the authorization code on a localhost loopback callback.
5. Exchanges the code for an access + refresh token and caches them in ~/.interviewlm/mcp-tokens.json (mode 0600).

On subsequent runs it uses the cached token (refreshing silently when expired) and immediately starts proxying.

Every JSON-RPC message from your local MCP client is forwarded transparently to POST https://interviewlm.com/api/mcp with a Bearer token, then the response is piped back over stdio. Token refresh and re-authentication on 401 are handled automatically.

Quick start

No install needed — run directly with npx:

npx @interviewlm/mcp

Your browser will open to InterviewLM's login/consent page. After authenticating, the shim starts silently and your MCP client can use it.

Client configuration

Claude Desktop / Claude.ai (pre-connector)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "interviewlm": {
      "command": "npx",
      "args": ["-y", "@interviewlm/mcp"]
    }
  }
}

Codex

Add to ~/.codex/mcp.json (or the equivalent config file for your Codex version):

{
  "mcpServers": {
    "interviewlm": {
      "command": "npx",
      "args": ["-y", "@interviewlm/mcp"]
    }
  }
}

GitHub Copilot (VS Code MCP extension)

In your VS Code settings.json:

{
  "mcp.servers": {
    "interviewlm": {
      "command": "npx",
      "args": ["-y", "@interviewlm/mcp"]
    }
  }
}

Cursor

In .cursor/mcp.json:

{
  "mcpServers": {
    "interviewlm": {
      "command": "npx",
      "args": ["-y", "@interviewlm/mcp"]
    }
  }
}

Self-hosted / staging

Override the base URL via an environment variable or a CLI flag:

# Environment variable
INTERVIEWLM_URL=https://staging.interviewlm.com npx @interviewlm/mcp

# CLI flag
npx @interviewlm/mcp --url https://staging.interviewlm.com

In a client config:

{
  "mcpServers": {
    "interviewlm": {
      "command": "npx",
      "args": ["-y", "@interviewlm/mcp", "--url", "https://your-instance.example.com"]
    }
  }
}

Token storage

Tokens are stored in ~/.interviewlm/mcp-tokens.json with file mode 0600 (readable only by the current user). To revoke access, delete this file or use Settings → Connected Apps in the InterviewLM web app.

Scopes requested

| Scope | What it covers | |---|---| | pipelines:read | List and view pipelines, stages, templates | | pipelines:write | Create and update pipelines, JD tools | | candidates:read | View candidates, status, activity | | candidates:write | Add, import, invite, advance candidates | | results:read | Evaluations, reports, replay manifests | | analytics:read | Analytics overview, leaderboard | | org:read | Org profile, team, credit balance |

The candidates:decide scope (hire/reject) is not requested by default. Request it explicitly if needed by your workflow.

Requirements

• Node.js >= 18.0.0
• A browser (for the one-time authentication flow)

How it connects

Your MCP client (stdio)
   ↓ JSON-RPC over stdin/stdout
@interviewlm/mcp shim
   ↓ POST /api/mcp  (Authorization: Bearer <token>)
https://interviewlm.com/api/mcp   ← Streamable HTTP MCP server
   ↓ Prisma / BullMQ / service layer
InterviewLM platform

Native MCP clients (Claude.ai, Cursor with remote MCP support) can connect directly to https://interviewlm.com/api/mcp without this shim — see the InterviewLM docs for the native connector setup.