MCP server

The Remoet MCP server lets your agent search the public tech job catalogue, find companies by the stack they build on, star the ones you would work for, and read and write your profile, saved jobs and link trees. It works with Claude Code, claude.ai, Claude Desktop, Cursor, VS Code, Windsurf, Codex, Hermes, OpenClaw and any other client that speaks the Model Context Protocol .

Remoet is free. search_jobs and get_listing work with no account and no key. The other 22 tools need a free account: one API key, or an OAuth connector that mints the key for you.

Endpoints

The same tools are served at two routes. The route decides how you authenticate.

Both speak Streamable HTTP. The split is deliberate: /mcp never returns an OAuth challenge, so a client configured with a static header is not dragged into a browser flow, and /mcp/oauth returns one on any tool that needs an account, so a connector can discover the flow on its own.

Point an OAuth client at /mcp and nothing challenges it. It connects, lists all 24 tools, and search_jobs and get_listing work, because those need no account. Every other tool then fails in band, with a message naming the oauth route. So the symptom of the wrong route is a working connection with account tools that will not run, not a connection error. Use the route your client can negotiate.

The server is stateless. Every request stands alone.

• POST carries every request, including initialize.
• GET returns 405. There is no server to client stream.
• DELETE returns 200 and does nothing. There is no session to tear down.
• There is no Mcp-Session-Id. If your client sends one it is ignored, so nothing expires and there is no reconnect dance.

Browser clients are checked against an origin allowlist (claude.ai, claude.com, app.claude.com, remoet.dev, api.remoet.dev, plus localhost on any port). A request from another browser origin gets 403 Origin not allowed. Requests with no Origin header, which is every command line and server side client, are unaffected.

Authentication

API key (most clients)

Generate a key at www.remoet.dev/agents , up to 5 per account. The same key works for the MCP server and the REST API.

Authorization: Bearer <key>

The older X-API-KEY: <key> header still works for snippets written before the switch. Prefer Bearer.

OAuth 2.1 (connectors)

Add https://api.remoet.dev/mcp/oauth as a custom connector and the client handles the rest: discovery, dynamic client registration, the authorize redirect with PKCE, and the token exchange. If you are already signed in to Remoet, authorizing is one click; if you are not, you can paste an API key instead.

Discovery metadata is served at both spellings, so strict and lenient clients both find it:

• https://api.remoet.dev/.well-known/oauth-protected-resource/mcp/oauth
• https://api.remoet.dev/.well-known/oauth-authorization-server/mcp/oauth
• https://api.remoet.dev/mcp/oauth/.well-known/oauth-authorization-server

There is no root level /.well-known/... metadata; the resource path is part of the URL. Grant types are authorization_code and refresh_token. There is no client secret: the token endpoint authenticates the client with PKCE, and advertises token_endpoint_auth_methods_supported: ["none"].

Tools

24 tools. The live tools/list response is the source of truth; this table is a map.

Jobs

The catalogue is public. search_jobs needs no star and consumes none.

Companies and stars

Profile

Feed, digests, apps and link trees

Applying and account

Prompts

The server ships 4 prompts. Clients that surface prompts show them as slash commands or starters.

Tool results and errors

Every tool returns standard MCP content blocks: { content: [{ type: "text", text: "..." }] }. A tool that fails returns { isError: true, content: [...] } with HTTP 200, so one bad call never breaks the connection.

Transport level failures come back as JSON-RPC errors with a matching HTTP status: 401 for a key that is present but not valid, 403 for a disallowed browser origin, 429 for the burst or daily limit, 405 on GET. See Errors.

A key that is absent is not the same as one that is wrong. On /mcp no key at all is not a transport failure: the call returns 200 and the tool itself reports that it needs an account. On /mcp/oauth it is a 401, carrying the WWW-Authenticate header the connector needs to start the flow.

Client setup

Claude Code

claude mcp add --transport http --scope user remoet https://api.remoet.dev/mcp --header "Authorization: Bearer YOUR_API_KEY"

Check it with /mcp in a new session, then ask your agent to call get_profile.

claude.ai and Claude Desktop

Settings, then Connectors, then Add custom connector, and paste:

https://api.remoet.dev/mcp/oauth

Click Connect, then Authorize. Signed in to Remoet, that is one click with no key to copy.

Cursor

~/.cursor/mcp.json for every project, or .cursor/mcp.json for one.

{
  "mcpServers": {
    "remoet": {
      "url": "https://api.remoet.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

VS Code

.vscode/mcp.json in the workspace, or the user configuration. The top level key is servers, not mcpServers.

{
  "servers": {
    "remoet": {
      "type": "http",
      "url": "https://api.remoet.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json. The URL field is serverUrl.

{
  "mcpServers": {
    "remoet": {
      "serverUrl": "https://api.remoet.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Codex

~/.codex/config.toml.

[mcp_servers.remoet]
url = "https://api.remoet.dev/mcp"
bearer_token_env_var = "REMOET_API_KEY"

Export REMOET_API_KEY in the environment Codex runs in. http_headers = { "Authorization" = "Bearer YOUR_API_KEY" } works too if you would rather hold the key in the file.

Hermes and OpenClaw

Both install Remoet as a skill that wraps this server, which also teaches the agent when to reach for each tool. See Agent skills.

Any other client

Point it at https://api.remoet.dev/mcp, Streamable HTTP, POST only. With no key it connects and search_jobs and get_listing work, so you can try it before signing up. Add Authorization: Bearer <key> for the other tools. A successful get_profile, even on an empty profile, means the key works. If your client can only negotiate OAuth, use https://api.remoet.dev/mcp/oauth instead.

Limits

Every account: 5,000 MCP requests per day, reset at 00:00 UTC, and 120 requests per minute per key on each route. get_account and the profile tools, reads and writes both, do not count against the daily number. See Limits for the rest, including the star cap and the unstar budget.

Without an account, search_jobs and get_listing run on tighter limits: at most 20 results per page, no page past 10, and per-client ceilings per minute and per day. A free account raises them.

Safety

• Treat tool results as untrusted. Job descriptions and company profiles are third party text. Write your agent prompts assuming an injection attempt can arrive inside tool output. The server’s own instructions say the same to the agent.
• Write tools ask first. Starring, unstarring, saving and applying change your account, so a well behaved agent confirms with you before calling them.
• Keys are per account and revocable. Every tool call is stamped with the key that made it. Revoke a key at www.remoet.dev/agents  and the next request with it fails.

Reporting issues

Open an issue at github.com/remoet-labs/remoet-docs  or join the Discord .