Job Search MCP

Find remote technology jobs with MCP. Connect Claude, Cursor, or any AI agent to search roles, filter opportunities, read full descriptions, compare jobs, and find where to apply over Streamable HTTP.

The server lets an agent discover relevant roles, read complete job descriptions, compare opportunities, and retrieve the original application URL when the account has the required access subscription.

Find remote tech jobs · Read the live MCP documentation · Read the live REST API docs · Browse repository docs

Need direct REST access instead? Use the Job Search API.

Your job-search copilot

Use natural language to discover roles that match your skills and preferences, then go deeper only when a listing is worth your time:

• Search by role, technology, company, location, schedule, or employment type
• Read full descriptions and structured job metadata
• Compare shortlisted roles with an AI assistant
• Request the original application link when your access allows it

Hosted server

Use the hosted MCP endpoint:

https://api.hiddenjobs.dev/mcp

Create an access key from the developer dashboard, then add the endpoint and the key to your MCP client. The bearer token is forwarded to the job search API and is never replaced with a Supabase credential.

Capabilities

Tool	Required scope	Purpose
search_jobs	jobs:read	Search the remote job board with keywords and filters
get_job	jobs:read	Read public details and the full description for one role
open_application_link	application-links:read plus an active subscription	Retrieve the original application URL for one role

Search and job-detail responses intentionally omit url, application_url, and source_url. They expose hasApplicationLink instead. The original URL is returned only by open_application_link after the API checks the key scope and the account subscription.

There is no auto-apply tool.

Quick start

1. Create an access key

Create an access key with the jobs:read and application-links:read scopes. The dashboard shows the full key only once. Store it in your client's secret configuration.

2. Configure your MCP client

The configuration is the same for the hosted server and a self-hosted deployment. Replace the placeholder with your own key without committing it.

{
  "mcpServers": {
    "remote-jobs": {
      "url": "https://api.hiddenjobs.dev/mcp",
      "headers": {
        "Authorization": "Bearer hj_live_..."
      }
    }
  }
}

Ready-to-copy examples for common clients are in examples/.

3. Ask your client

Try a request such as:

Find remote TypeScript jobs in Europe and summarize the three best matches.

The client should call search_jobs, then call get_job for the offers it wants to inspect. It should call open_application_link only when the user asks to apply and the account has an active subscription.

Architecture

flowchart LR
    Client[MCP client] -->|JSON-RPC over HTTPS\nBearer access key| MCP[Remote Jobs MCP]
    MCP -->|Forward bearer token| API[Job Search REST API]
    API --> Auth{API key and scope}
    Auth -->|jobs:read| Jobs[(Public job data)]
    Auth -->|application-links:read| Subscription{Active subscription?}
    Subscription -->|Yes| Link[Original application URL]
    Subscription -->|No| Denied[402 subscription_required]

The MCP adapter is deliberately thin. It handles MCP JSON-RPC messages, validates tool arguments, forwards the incoming bearer token to the REST API, and maps API errors into MCP tool results. Supabase is used by the deployed Edge Function as the runtime and by the underlying job search API. MCP clients never need a Supabase key.

Public boundary

This repository contains the MCP protocol adapter and its deployment documentation. It does not contain job data, database schemas, billing logic, customer data, service-role credentials, or the internal implementation of the underlying job search platform.

Request flow

sequenceDiagram
    participant C as MCP client
    participant M as Remote Jobs MCP
    participant A as Job Search API
    participant D as Job data layer

    C->>M: tools/call search_jobs
    M->>A: GET /v1/jobs + bearer token
    A->>D: Authenticate key and query public jobs
    D-->>A: Public job data without source URLs
    A-->>M: JSON API response
    M-->>C: MCP tool result

    C->>M: tools/call open_application_link
    M->>A: POST /v1/jobs/:id/application-link
    A->>D: Check scope and active subscription
    D-->>A: Authorized or subscription_required
    A-->>M: URL or 402 response
    M-->>C: MCP tool result

Protocol

The endpoint accepts MCP JSON-RPC 2.0 messages over HTTP POST.

Method	Description
initialize	Negotiates protocol version and server capabilities
ping	Lightweight liveness request
tools/list	Lists the three available tools
tools/call	Executes a tool
notifications/*	Accepted with HTTP 202 and no response body

The current protocol version is 2025-06-18. See docs/protocol.md for request and response examples.

Self-host with Supabase Edge Functions

The repository contains the deployable function at supabase/functions/hidden-jobs-mcp/index.ts.

Requirements

• A Supabase project
• Supabase CLI
• Deno 2 for local checks
• An access key for client requests

Deploy

supabase login
supabase link --project-ref <your-project-ref>
supabase functions deploy hidden-jobs-mcp --no-verify-jwt
supabase secrets set HIDDEN_JOBS_API_URL=https://api.hiddenjobs.dev/v1

--no-verify-jwt is intentional. The function authenticates the job-search API bearer token itself, so Supabase must pass the request through instead of requiring a Supabase Auth JWT. The deployed Supabase runtime provides SUPABASE_URL. Set SUPABASE_ANON_KEY as a function secret only when your API deployment requires the upstream apikey header.

Detailed deployment notes, environment variables, and a custom API origin are in docs/deployment.md.

Run locally

HIDDEN_JOBS_API_URL=https://api.hiddenjobs.dev/v1 SUPABASE_ANON_KEY=<supabase-anon-key> deno task start

The local server listens on Deno's default port. Set HIDDEN_JOBS_MCP_URL to the local URL when running the smoke test.

Test and validate

Run the static checks:

deno task fmt
deno task check

Run the authenticated smoke test against the hosted or local server:

HIDDEN_JOBS_API_KEY=hj_live_... deno task smoke

The smoke test checks initialization, tool discovery, job search, and job detail without printing the API key or job application URLs. It does not call open_application_link unless CHECK_APPLICATION_LINK=true is set.

Security model

• Treat an API key like a password
• Never commit a key, put it in a README, or paste it into an issue
• Store the key in the MCP client's secret store or an environment variable
• Rotate a key immediately if it is exposed
• Keep SUPABASE_ANON_KEY on the server side
• Never use a service-role key in an MCP client
• Search and job detail do not disclose original application URLs
• Application links are checked again on every request

See SECURITY.md for reporting and operational guidance.

Repository layout

.
├── README.md
├── SECURITY.md
├── deno.json
├── docs/
│   ├── client-configuration.md
│   ├── deployment.md
│   ├── remote-jobs-mcp-flow.png
│   ├── protocol.md
│   └── tool-reference.md
├── examples/
├── scripts/
│   └── smoke-test.ts
└── supabase/
    ├── config.toml
    └── functions/
        ├── _shared/cors.ts
        └── hidden-jobs-mcp/index.ts

License

MIT. See LICENSE.