Choose your credential model

Set up personal access tokens (admin)

1. Ask Eightfold to enable MCP for your tenant (request mcp_gate).
2. Once enabled, admins can change the default expiry, the maximum expiry, or the per-user token limit — or turn PATs off entirely. These settings live in oauth_v2_config, which Eightfold edits on request.
3. Review which permission sets (scope groups) users will see. The permissions picker only shows groups the user qualifies for: Talent Management for all employees; Talent Acquisition for recruiters, admins, and hiring managers (no tools in this release); Resource Management where RM is enabled. For this rollout, set up Talent Management only.
4. Share the /oauth/tokens link with users. Optionally, add a link in Career Hub so users can reach it from Career Hub → Settings → Account. To configure this: in Career Hub base config → advanced section in the Admin Console, add tokenManagement to the account settings field ordering.

Career Hub base config — adding tokenManagement to account settings field ordering

5. Verify: have a test user create a token, copy the MCP URL and list the tools, and confirm the call appears in Data Hub.

Path A — Get a PAT (self-serve)

1. Open the token management page at /oauth/tokens.
2. Click Create token — give it a name and pick a scope group.
3. Copy the token — it's shown only once. Copy the MCP server URL shown on the same page — this is the URL your AI client connects to.
4. Paste it into your MCP client as an Authorization: Bearer <token> header.

The /oauth/tokens page — click Create token, name it, and pick a scope group

Path B — Register an OAuth client (admin)

Access the OAuth Client Manager

1. Log in and open the Admin Console.
2. In the left navigation, expand the Integration group.
3. Click Eightfold MCP (listed below "Eightfold API").

The Registered clients page opens — a table of existing clients plus a Register client button. If mcp_gate is off, this nav item is hidden entirely — request the gate from the Eightfold team first. If you aren't a tenant admin, the page may load but client data won't.

The Registered clients page — existing clients listed with Register client button

Register a client — 3-step wizard

Step 1: Client information — enter name, scopes, and access token expiry

Three authentication methods

Step 2: Authentication — choose Client secret (basic/post) or Private key JWT

Grant types & validation rules

Registration is rejected if you violate one:

• authorization_code requires at least one redirect URI.
• authorization_code requires refresh_token too.
• Secret-based methods cannot use the jwt-bearer grant.
• Private key JWT requires at least one public key.
• jwt_issuer and idp_public_keys are provided together or not at all.
• Refresh-token expiry must exceed access-token expiry; access-token expiry is required and capped at the platform maximum.
• At least one scope must be requested.

You can register at most 10 clients per tenant — delete one to free a slot.

Edit and delete a client

Editing doesn't re-issue the secret. Editing allowed scopes only affects new tokens — already-issued tokens keep their original scope until they expire.

Delete a client: click delete (trash), confirm. Can't be undone from the UI. Soft-deletes the client (no new tokens), but already-issued tokens keep working until they expire naturally (~1 hour).

Gating & visibility

Method C in full — Private key JWT

No shared secret ever leaves you. Generate an RSA key pair locally and register only the public key. Your client signs a short-lived JWT assertion with the private key; Eightfold verifies it with the registered public key. Supported algorithms: RS256, RS384, RS512.

Quick start (6 steps)

1. Generate RSA key pair (private.pem, public.pem).
2. Share the public key + client name with Eightfold → receive client_id.
3. Create a client assertion JWT, signed with your private key.
4. Create a JWT assertion on behalf of the user (or have your IDP share one, if registered with the client).
5. Exchange both JWTs at the Eightfold OAuth Token Endpoint → receive an access token.
6. Call the MCP server with Authorization: Bearer <token>.

Step 1 — Generate your key pair

# Generate a 2048-bit RSA private key
openssl genrsa -out private.pem 2048
# Extract the public key
openssl rsa -in private.pem -pubout -out public.pem

Store private.pem securely (never commit to Git). Share only public.pem with Eightfold. The private key signs JWTs; the public key is what Eightfold uses to verify them.

Step 2 — Register your client

Client registration is self-service in the Admin Console — no engineering ticket needed. It requires mcp_gate to be enabled for your tenant.

1. Log in and open the Admin Console.
2. In the left navigation, expand Integration and click Eightfold MCP.
3. On the Registered clients page, click Register client.
4. Client information: enter Client name, Description, Logo URL, Homepage URL, Scopes, and Access token expiry.
5. Authentication: choose Private key JWT. Paste the full public_key.pem block into Client public keys. Give it a Key ID (kid) — any unique label, e.g. key-1.
6. Access grant: choose jwt-bearer as the grant type (preferred). You can optionally also enable authorization_code + refresh_token.
7. Self-issued (default, recommended): leave JWT Issuer blank — it defaults to your client_id. External IdP (e.g. Entra ID): set JWT Issuer and IDP public keys instead.
8. On the success screen, copy the client_id. No secret is generated for this method.

Step 3 — Create a client assertion JWT

# pip install pyjwt cryptography requests
import jwt
import datetime
import uuid

with open("private.pem", "rb") as f:
    private_key = f.read()

CLIENT_ID_FROM_EIGHTFOLD = ""
now = datetime.datetime.utcnow()
client_assertion_payload = {
    "iss": CLIENT_ID_FROM_EIGHTFOLD,   # client_id
    "sub": CLIENT_ID_FROM_EIGHTFOLD,   # must match iss
    "aud": "urn:eightfold:oauth-server:token-endpoint",
    "jti": str(uuid.uuid4()),          # unique — prevents replay
    "exp": now + datetime.timedelta(minutes=5),  # max 5 min from iat
    "iat": now,
}
client_assertion = jwt.encode(client_assertion_payload, private_key, algorithm="RS256", headers={"kid": "key-1"})
print(client_assertion)

Rules: never reuse assertions (unique jti every time); exp must be ≤ 5 minutes after iat; sign only with RS256/RS384/RS512; aud must always be urn:eightfold:oauth-server:token-endpoint; iss must match sub, both equal to your client_id. Include kid in the header if you have multiple registered keys (optional with just one).

Step 4 — Create a JWT assertion on behalf of the user

If an IDP is involved, this assertion must be signed by the IDP. Otherwise, sign it yourself:

CLIENT_ID_FROM_EIGHTFOLD = ""
EIGHTFOLD_USER_EMAIL = "Eightfold_User_Email"
now = datetime.datetime.utcnow()
jwt_assertion_payload = {
    "iss": CLIENT_ID_FROM_EIGHTFOLD,   # client_id or IDP issuer
    "sub": EIGHTFOLD_USER_EMAIL,
    "aud": "urn:eightfold:oauth-server:token-endpoint",
    "jti": str(uuid.uuid4()),
    "exp": now + datetime.timedelta(minutes=5),
    "iat": now,
}
jwt_assertion = jwt.encode(jwt_assertion_payload, private_key, algorithm="RS256", headers={"kid": "key-1"})

Same rules as Step 3, plus: iss must match the IDP issuer claim from client registration; sub can be the Eightfold user email, or email:group_id (e.g. demo@eightfold.com:eightfold.com).

Step 5 — Exchange both JWTs for an access token

curl -X POST https://app.eightfold.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  -d "assertion=$JWT_ASSERTION" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=$CLIENT_ASSERTION"

Or in Python:

import requests
token_endpoint = 'https://app.eightfold.ai/oauth/token'
data = {
    'grant_type': 'urn:ietf:params:oauth:grant-type:jwt-bearer',
    'assertion': jwt_assertion,
    'client_assertion_type': 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
    'client_assertion': client_assertion,
}
response = requests.post(token_endpoint, data=data, headers={'Content-Type': 'application/x-www-form-urlencoded'})
response.raise_for_status()
print(response.json())

Sample response:

{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN_HERE", "expires_in": 3600 }

Use https://app.eightfold.ai/oauth/token or your https://customer-domain.eightfold.ai/oauth/token.

Step 6 — Test the connection

Python:

# pip install mcp  (version > 1.9, supports streamablehttp_client)
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client as http_client

SERVER_URL = 'https://mcp.eightfold.ai/mcp/'

async def main():
    headers = {'Authorization': 'Bearer (access token obtained from OAuth server)'}
    async with http_client(SERVER_URL, headers=headers) as transport_layer:
        read, write, _ = transport_layer
        async with ClientSession(read, write) as session:
            await session.initialize()
            print(await session.list_tools())

if __name__ == '__main__':
    asyncio.run(main())

Cursor AI Editor config:

{
  "mcpServers": {
    "eightfold": {
      "url": "https://mcp.eightfold.ai/mcp/",
      "headers": { "Authorization": "Bearer (mcp_token)" }
    }
  }
}

Complete OAuth client configuration reference

Connect a specific client

Claude — detailed setup

Part 1 — Eightfold admin registers an OAuth client for Claude

1. Sign in to Eightfold and open the Admin Console.
2. Go to Integrations → Eightfold MCP, then click Register client.
3. Client information:
   • Client name: for example, "Claude". Users see this name on the Eightfold consent screen.
   • Description, Logo URL, Homepage URL: optional.
   • Scopes: talent_management.
   • Access token expiry (seconds): keep 3600 (the maximum).
4. Authentication: set Authentication method to Client secret (post).
5. Access grant:
   • OAuth flow: Authorization Code.
   • Redirect URIs: https://claude.ai/api/mcp/auth_callback, exactly as shown.
   • Refresh token expiry (seconds): keep 2592000 (30 days).
   • Disable PKCE: leave it unchecked. Claude always uses PKCE.
6. Click Register. On "Client registered successfully", copy the Client ID and Client secret. The secret is shown only once — if it's lost, delete the client and register a new one.
7. Send the Client ID, the secret, and your region's MCP URL to your Claude Owner through a secure channel such as a password manager. Don't use email or chat.

Step 3: Access grant — set redirect URI to https://claude.ai/api/mcp/auth_callback

Part 2 — Claude Owner adds the connector

1. In Claude, go to Organization settings → Connectors.
2. Click Add, choose Custom, and if asked for the type, choose Web.
3. Enter a name (for example, "Eightfold"). Users see it in their connectors list.
4. Enter the MCP server URL for your region exactly as shown, including the trailing /. Click Continue.
5. Authentication: choose Sign in now.
6. OAuth client: choose Use your own OAuth client, then enter the Client ID and Client secret from Part 1. Don't choose "Use Claude's published identity" or "Register automatically" — Eightfold doesn't support those.
7. Leave Request headers empty and click Add.

The connector now appears for everyone in your organization with a Custom label.

Part 3 — Each user connects

1. In Claude, go to Customize → Connectors.
2. Find the Eightfold connector (marked Custom) and click Connect.
3. Sign in to Eightfold if asked, with your employee account.
4. On the Eightfold consent screen, check the scopes listed and click Allow.
5. You're returned to Claude. Open the connector to see the tools available to you.

Claude Code (CLI) — setup with a PAT

1. Create a personal access token: open your Career Hub → Settings → Token management console, create a Talent Management token, and copy it.
2. In your terminal, add the server:

   claude mcp add --transport http eightfold_production https://mcp.eightfold.ai/mcp/ --header "Authorization: Bearer <token>"

   Replace <token> with the token you copied.
3. Verify the connection: run claude in your terminal, then type /mcp. Check that eightfold_production appears in the server list.

GPT

The following steps are possible for Admin only.

1. In ChatGPT, go to Settings → Plugins, then click Browse plugins.
2. Click + to start a new plugin.
3. Enter a Name and optional Description, set Connection to Server URL, and set Authentication to OAuth.
4. Open Advanced OAuth settings and copy the auto-generated Callback URL — you'll need it when registering the client in Eightfold.
5. In the Eightfold Admin Console, register the OAuth client and paste this Callback URL into Redirect URIs. Use the client secret post method, and leave PKCE disabled for GPT (unlike Claude, where PKCE stays enabled).
6. Back in ChatGPT, paste the Client ID and Client Secret from Eightfold, and set Token endpoint auth method to client_secret_post.
7. Check "I understand and want to continue" to accept the custom-MCP-server risk notice, then click Create.
8. Click Sign in with [connector name]. You'll be redirected to Eightfold's consent screen — review the requested scopes and click Allow.
9. Once installed, open the connector's settings and click Refresh under Actions. The tool list is empty until you do this.
10. To use the connector in a chat, type @ followed by its name (e.g. @My EF MCP what should be my next roles?).

Microsoft Copilot Studio — full walkthrough

Pieces involved: MCP server (region-dependent URL) · OAuth client · Tool/connector · Connection · Agent.

Reference values

Steps

1. Register the OAuth client in Eightfold first. Admin Console → Integration → Eightfold MCP → Add client. Set Token endpoint authentication method to Client secret post. Disable PKCE. Enter a placeholder Redirect URI — you'll replace it in Step 5. Set Scopes. Save and copy Client ID and Client secret.
2. Copilot Studio → Tools → New tool → Model Context Protocol.
3. Name it, set Server URL to https://mcp.eightfold.ai/mcp/, Authentication → OAuth 2.0, Type → Manual. Fill in Client ID/secret/URLs/Scopes from the reference table. Leave Redirect URI blank.
4. Click Create — Copilot Studio generates a Redirect URL.
5. Update the Redirect URI on your Eightfold client: open the tool's Security tab, copy the generated URL; go back to Admin Console → Edit the client → Access grant step → paste it in → Save.
6. Create and authorize the connection: Test step → Update connection → New connection → review the Eightfold consent screen → Allow → close the editor.
7. Agents → open/create an agent → Tools → Add a tool → choose yours → Add.
8. Ask a test query (e.g. "give me the top 10 Python jobs in the USA"). Results = connected.
9. If you see "Let's get you connected first…": open Connection Manager, connect, retry.

Troubleshooting

Set up any other client

Enable MCP for a brand-new tenant

Same procedure for production or sandbox — sandbox tenants share the regional deployment, nothing extra to provision.

New tenant MCP enablement checklist

Quick recipes

• Enable a tenant, PAT-only (fastest pilot path): request mcp_gate from the Eightfold team → leave oauth_v2_config alone → mint a token at /oauth/tokens. Set the scope group to talent_management only — other scope groups (such as talent_acquisition) have no enabled tools yet.
• Add OAuth client registration: do the above (mcp_gate already turns this on), then confirm the registering person is a group admin.
• Give a tenant a custom scope group or longer-lived tokens: go to Admin Console → Integration → Eightfold MCP → Settings → Configuration and update the Scope Groups or Personal Access Tokens settings there.
• Audit a change: run get_changelog on the config name, optionally filtered by partition.