@aiesphere/mcp-connect

Connect the AiESphere MCP server to your AI client in one command — so your agent can fetch your recommended jobs, tailor your résumé, and one‑click apply, all through the platform's grounded, verified engine.

npx @aiesphere/mcp-connect

It checks the server is up, works out which AI clients you actually have installed, and opens the picker with those already ticked. Move with ↑ ↓, toggle with space (or tab), type to filter, enter to confirm. Usually that means pressing enter once.

It then writes the right config for each client you chose, backing up anything it touches, and points them at https://mcp.aiesphere.com/mcp. Reopen the client and it opens a browser to sign in to AiESphere and approve access (OAuth 2.1).

    ███   █████  █████  █████  ████   █   █  █████  ████   █████
   █   █    █    █      █      █   █  █   █  █      █   █  █
   █████    █    ████   █████  ████   █████  ████   ████   ████
   █   █    █    █          █  █      █   █  █      █  █   █
   █   █  █████  █████  █████  █      █   █  █████  █   █  █████

   the job-apply backend for any AI agent

┌   aiesphere
│
◇  Server  https://mcp.aiesphere.com/mcp
│
◇  Reachable  OAuth 2.1 · 13 scopes
│
◇  Found on this machine, already selected ─╮
│  ● Claude Code (CLI)                      │
│  ● Cursor                                 │
│  ● Codex (OpenAI CLI)                     │
├───────────────────────────────────────────╯
│
◆  Which clients should connect to AiESphere?
│  Search: Type to filter…
│  ◼ Claude Code (CLI)
│  ◼ Cursor
│  ◼ Codex (OpenAI CLI)
│  ◻ Claude Desktop
│  ◻ VS Code (GitHub Copilot, agent mode)
│  ↑/↓ to navigate • Space/Tab: select • Enter: confirm • Type: to search

Non‑interactive / scripted:

npx @aiesphere/mcp-connect --all                  # every client found on this machine
npx @aiesphere/mcp-connect --client cursor        # write config for one client
npx @aiesphere/mcp-connect --client codex --print # just show the config, don't write
npx @aiesphere/mcp-connect --list                 # list clients, marking the ones found

Flags: --client <id> · --all · --url <url> · --name <server> · --print · --list · --help

Supported clients

| Client | How it connects | |---|---| | Claude Code | native remote (claude mcp add --transport http) or project .mcp.json | | Claude Desktop | mcp-remote bridge (OAuth) in claude_desktop_config.json | | Cursor | native remote URL in ~/.cursor/mcp.json | | VS Code (GitHub Copilot) | native remote in .vscode/mcp.json (or code --add-mcp) | | Windsurf | serverUrl in ~/.codeium/windsurf/mcp_config.json | | Cline | native streamableHttp in cline_mcp_settings.json | | Zed | native remote url in ~/.config/zed/settings.json (Zed runs the OAuth flow) | | opencode | native remote in ~/.config/opencode/opencode.json | | Codex (OpenAI CLI) | native remote url in ~/.codex/config.toml (current Codex; older needs experimental_use_rmcp_client) | | Gemini CLI | native httpUrl in ~/.gemini/settings.json | | Anything else | npx -y mcp-remote https://mcp.aiesphere.com/mcp |

Because AiESphere ships a standard remote MCP server (Streamable HTTP + OAuth 2.1 with dynamic client registration), any MCP‑capable client works with the same one URL — no per‑client server code. Clients that only speak stdio (or don't do OAuth themselves) use the widely‑used mcp-remote bridge, which runs the OAuth browser flow and proxies it to stdio.

Manual (any client)

Native remote (Cursor / VS Code / opencode / Gemini CLI / Claude Code):

{ "mcpServers": { "aiesphere": { "url": "https://mcp.aiesphere.com/mcp" } } }

Stdio bridge (Claude Desktop / Codex / Zed / anything):

{ "mcpServers": { "aiesphere": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.aiesphere.com/mcp"] } } }

What you can do once connected

Tools

| Area | Tools | |---|---| | Jobs | list_recommended_jobs · search_jobs · get_job · get_apply_eligibility · save_job · dismiss_job | | Profile | get_profile · list_resumes · get_apply_profile · update_apply_profile | | Applications | list_applications · list_apply_runs · get_apply_status · update_application_status · add_application_note · archive_application | | Applying | apply_to_job · confirm_submit | | Documents | preview_tailoring · generate_cover_letter | | Connectivity | ping |

Reads are annotated read-only so most clients run them without prompting. apply_to_job and confirm_submit are annotated destructive — they file a real application in your name.

Resources — profile://me · resumes://list · applications://board, for pinning your own state into a conversation instead of re-fetching it.

Prompts (slash commands in most clients) — apply-to-best-matches · tailor-for-job · review-pipeline · unstick-apply-run.

Applying end to end

apply_to_job returns a runId immediately. Pass wait: true to follow the run instead: it streams MCP progress notifications, and if the application stalls on a screening question the engine won't guess at, it asks you through your client (elicitation) and finishes the submission. Clients without elicitation support get the outstanding questions back and can answer them with confirm_submit(runId, answers).

Résumé tailoring and cover letters are always generated server-side, grounded in your résumé and the job description and checked against fabrication. The connected model steers; it never writes the document that gets submitted.

Scopes

jobs.read · jobs.write · profile.read · profile.write · applications.read · applications.write · resume.tailor · cover.generate · apply.submit

A client that requests no scopes gets read-only access. Writing, tailoring and — especially — apply.submit must be requested explicitly, and the consent screen lists exactly what was asked for before you approve. Revoke any agent any time from Settings → Connected apps.

Developing against a local server

npm run dev:next     # the MCP endpoint is served at http://localhost:3000/mcp
npx tsx --env-file=.env scripts/mcp-server/verify-tools.mts          # surface + gate checks
npx tsx scripts/mcp-server/verify-client-matrix.mts http://localhost:3000/mcp

The repo's own .mcp.json points at the local endpoint, so Claude Code picks the server up from the project root. The flow is OAuth, so there is nothing secret in that file.

Config formats track each client's current docs and can shift between versions. If a client updates its schema, run with --print and paste the snippet, or use the mcp-remote bridge.