Agentic Data Plane

Greenhouse Managed MCP Server

The Greenhouse managed MCP server lets agents work with your Greenhouse recruiting data. With it, an agent can list and look up jobs, candidates, and applications, and create candidates.

After reading this page, you will be able to:

  • Configure the Greenhouse managed MCP server with OAuth client credentials or per-user OAuth

  • Choose the Greenhouse user the server acts as and the credential scopes its tools need

  • Update agents written for the earlier Greenhouse tools to the cursor-paged tools

What this MCP server does

The server calls the Greenhouse Harvest v3 API. It authenticates in one of two ways:

  • OAuth client credentials: A Harvest V3 (OAuth) API credential that you create in Greenhouse. Every caller of the server shares it. Use this method unless you have a Greenhouse partner OAuth client.

  • User OAuth: Each user connects their own Greenhouse account through an OAuth provider. Greenhouse issues the OAuth clients this flow needs only to its partners. See Use per-user OAuth instead.

Greenhouse attributes every read and write to the user that the token represents, and applies that user’s permissions.

Prerequisites

Before you create the server, make sure you have:

  • Permission in Greenhouse to create API credentials.

  • The numeric user ID of a Greenhouse Site Admin, if the server should act as that user instead of the credential’s integration user. See Choose the user the server acts as.

  • Access to the Agentic Data Plane secret store, which holds the credential’s client secret. See Manage Secrets.

Get Greenhouse credentials

Create a Harvest V3 (OAuth) API credential in Greenhouse:

  1. In Greenhouse, open API Credentials and click Create new API credentials.

  2. Select Harvest V3 (OAuth) and save the credential.

  3. Note the client ID and client secret.

  4. Configure these scopes on the credential:

    • harvest:jobs:list

    • harvest:candidates:list

    • harvest:applications:list

    • harvest:candidates:create, only if agents should create candidates

  5. Store the client secret in the Agentic Data Plane secret store under an UPPER_SNAKE_CASE name, for example GREENHOUSE_CLIENT_SECRET.

You manage the scopes on the credential in Greenhouse. The server doesn’t request scopes of its own. Leave out a scope, and the tools that need it fail.

Choose the user the server acts as

On Behalf Of User ID decides which Greenhouse user the server acts as:

  • 0 (the default): The integration user that Greenhouse created with the credential. It has access across your Greenhouse organization.

  • A Site Admin’s numeric user ID: Requests run as that Site Admin and see only what that user can see in Greenhouse. Candidates the server creates are attributed to that user. Greenhouse requires a Site Admin for list requests, so don’t enter the ID of a user who isn’t one.

Some private data, such as private fields, needs an advanced permission in Greenhouse. If the user the server acts as doesn’t have it, Greenhouse leaves that data out of results.

Use per-user OAuth instead

Greenhouse issues OAuth clients for per-user authorization only to Greenhouse partners with a signed partnership agreement. If you have one, set it up this way:

  1. Ask Greenhouse partner support to register your AI Gateway OAuth callback as a redirect URI (typically https://aigw.<cluster-id>.clusters.rdpa.co/oauth/v1/callback).

  2. In Agentic Data Plane, create a custom OAuth provider with:

    • Authorization endpoint: https://auth.greenhouse.io/authorize

    • Token endpoint: https://auth.greenhouse.io/token

    • Scopes: The scopes from Get Greenhouse credentials

    • The client ID and a secret-store reference for the client secret that Greenhouse issued

      See Configure an OAuth Provider.

With per-user OAuth, the server ignores On Behalf Of User ID. Each call runs as the user who connected.

Configure

Create a new Greenhouse MCP server in Agentic Data Plane:

  1. Open MCP servers in the sidebar.

  2. Click Add MCP server.

  3. Click the Greenhouse card in the marketplace picker.

  4. Replace the suggested Name, and optionally add a Description.

  5. In the Greenhouse configuration form:

    Field Notes

    On Behalf Of User ID

    0 to act as the credential’s integration user, or a Site Admin’s numeric user ID. See Choose the user the server acts as. Ignored with User OAuth.

    Max Results Per Page

    The largest page any list tool returns, from 1 to 500. A tool call can ask for a smaller page but not a larger one. The slider starts at 1, so set it to the page size you want, for example 100. Left at 1, every list tool returns one result per call.

    Auth

    OAuth for client credentials, or User OAuth for per-user OAuth.

    Client ID (OAuth)

    The client ID of your Harvest V3 (OAuth) credential.

    Client Secret Ref (OAuth)

    The secret-store name that holds the client secret, for example GREENHOUSE_CLIENT_SECRET.

    Token URL (OAuth)

    https://auth.greenhouse.io/token. Saving fails with any other URL.

    Scopes (OAuth)

    Leave empty. The server ignores this field and uses the scopes on the Greenhouse credential.

    OAuth Provider (User OAuth)

    The Greenhouse OAuth provider you configured.

    Required scopes (User OAuth)

    The scopes your agents need, from Get Greenhouse credentials. Every required scope must also be in the provider’s scopes. A required scope the provider doesn’t request makes tool calls fail with scope_upgrade_required until each user reconnects and grants it.

  6. Click Create server.

Configure from the CLI

Set the authentication method inside the --managed.config JSON. One of oauth or userOauth is required.

  • OAuth client credentials

  • User OAuth

rpk ai mcp-server create my-greenhouse --enabled --managed.config '{
  "@type": "type.googleapis.com/redpanda.mcps.greenhouse.v1.GreenhouseMCPConfig",
  "onBehalfOfUserId": "0",
  "maxResultsPerPage": 100,
  "oauth": {
    "clientId": "<greenhouse-client-id>",
    "clientSecretRef": "GREENHOUSE_CLIENT_SECRET",
    "tokenUrl": "https://auth.greenhouse.io/token"
  }
}'
rpk ai mcp-server create my-greenhouse --enabled --managed.config '{
  "@type": "type.googleapis.com/redpanda.mcps.greenhouse.v1.GreenhouseMCPConfig",
  "maxResultsPerPage": 100,
  "userOauth": {
    "providerName": "greenhouse",
    "requiredScopes": ["harvest:jobs:list", "harvest:candidates:list", "harvest:applications:list"]
  }
}'

userOauth.providerName is the resource name of the Greenhouse OAuth provider you created.

Tools

The Greenhouse MCP server exposes these tools:

Tool Description

list_jobs

List jobs, optionally filtered by status (open, closed, or draft).

get_job

Retrieve one job by job_id.

list_candidates

List candidates, optionally filtered by email. Greenhouse matches any of a candidate’s email addresses and ignores case. You can’t search candidates by name.

get_candidate

Retrieve one candidate by candidate_id.

list_applications

List applications, optionally filtered by job_id, candidate_id, and status (in_process, rejected, hired, or converted).

create_candidate

Create a candidate from first_name, last_name, and email, plus optional phone, company, and title. With job_id, the candidate applies to that job. Without it, Greenhouse creates the candidate as a prospect.

The list tools page with a cursor and return the newest records first. Each response includes next_cursor, which is empty on the last page. To read the next page, call the tool again with only cursor set to that value. The filters and page_size from the first call carry over, and a later call can’t change them. page_size can’t exceed the server’s Max Results Per Page.

Example: List a candidate’s applications

curl -s https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/my-greenhouse \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_applications",
      "arguments": {
        "candidate_id": 12345678,
        "status": "in_process"
      }
    }
  }'

Update agents written for the earlier tools

The Greenhouse tools now use Greenhouse’s Harvest v3 API, and some tool arguments and results changed. Update agents and prompts written for the earlier tools:

  • The list tools no longer take page. Page with cursor and next_cursor instead.

  • list_candidates no longer filters by job_id. To find the candidates for a job, call list_applications with job_id and read each application’s candidate_id.

  • Jobs carry department_id and office_ids instead of embedded offices and departments, and no longer include the hiring team.

  • Candidates no longer include application_ids. Call list_applications with candidate_id instead.

  • Applications carry job_id and source_id instead of the job name and source, and add stage_id. A prospect application has job_id 0.

Troubleshooting

Symptom What to check

Saving the server fails with a token_url error

Set Token URL to https://auth.greenhouse.io/token.

Every tool call fails with an authentication error

Check the client ID, and that the secret-store entry holds the credential’s current client secret. Confirm the credential is a Harvest V3 (OAuth) credential.

One tool fails while the others work

The credential is missing that tool’s scope. Add it in Greenhouse. See Get Greenhouse credentials.

List tools return one result per call

Max Results Per Page is set to 1. Edit the server and raise it.

List tools return nothing, or create_candidate fails with 403 Forbidden

On Behalf Of User ID names a user who isn’t a Site Admin or lacks a permission. Set it to a Site Admin’s ID, or to 0.

connection_required (User OAuth)

The user hasn’t connected Greenhouse yet. The failed tool result carries the authorization URL. After the user consents, later calls reuse the stored token.

Next steps