> ## Documentation Index
> Fetch the complete documentation index at: https://docs.exterview.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP protocol and authentication

> Discover and call Exterview MCP tools with OAuth and Streamable HTTP.

Use the MCP endpoint issued for your Exterview workspace. See [Connected Agent Access](https://docs.exterview.ai/guides/connected-agent-access.md) for client setup. The first Claude and ChatGPT directory release is planned as read-only.

## Authentication

Use a client that supports OAuth authorization for remote MCP servers. The client follows the server's advertised discovery and authorization metadata, starts the authorization code flow with PKCE, and sends a bearer token with MCP requests. The Exterview sign-in page offers the options configured for your workspace. These can include Microsoft sign-in or an Exterview email and password.

The access token identifies the workspace and caller. `exterview:read` is the read scope. Some deployments can grant `exterview:write` separately. Review the scopes actually granted, and request the minimum access needed. Follow the client's reauthorization flow when a grant expires or changes.

## Discover and call tools

Use an MCP SDK for Streamable HTTP. The gateway accepts MCP requests over HTTPS POST at the issued endpoint and uses JSON responses. Let the client negotiate the protocol version and handle authorization.

1. Send `initialize` and complete the initialization handshake.
2. Send `tools/list` and follow `nextCursor` if discovery returns one. Use the returned names and input schemas for your connection.
3. Send `tools/call` with the exact name and matching arguments. Reuse record IDs returned by earlier calls. Read the result content and check for errors before using any data.

Example JSON-RPC request after initialization. Use a connection that lists `list_jobs`.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_jobs",
    "arguments": { "limit": 5 }
  }
}
```

Use the client's bearer authentication and negotiated version. For a direct HTTP request, use `Content-Type: application/json` and `Accept: application/json, text/event-stream`. The current gateway returns tool payloads as JSON text in the MCP result content. Use the discovered schema for exact inputs and the [tool catalog](https://docs.exterview.ai/api-reference/mcp-tools.md) to browse available workflows.

## Errors and limits

| Result | What to do |
| - | - |
| HTTP `401` | Use OAuth discovery or reconnect. Verify the endpoint, account, and token audience. |
| Tool missing or access denied | Verify the workspace, role, and granted access. Rediscover tools after access changes. |
| Invalid arguments | Correct the fields against the advertised schema and tool constraints. |
| Empty, null, or partial result | Read the returned notes and coverage flags. A missing score or incomplete dataset can change the interpretation. |
| Rate limit, timeout, or transient service error | Follow any retry timing the response provides. Use bounded retries for reads. Before retrying a write on an authorized deployment, check the operation's documented retry behavior and the outcome of the first request. |

Use tool-specific page limits and opaque cursors. Request only the fields and scope needed for the workflow. A successful connection does not guarantee access to every record or tool. Share the correlation ID, if present, when escalating through your organization's support channel.

## Data handling

Use approved assistants and share hiring data only under your organization's data handling rules. Keep tokens and raw applicant records out of logs and support requests. See [Security](https://docs.exterview.ai/trust/security.md) for Exterview's platform controls.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.