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

# MCP Server

> Connect your AI assistant to Sentrion to search jobs, discover filters, and check credits

The Sentrion Model Context Protocol (MCP) server lets AI assistants search current
and historical job postings using your Sentrion account. It exposes eight tools
backed by the Sentrion API.

## Connect to Sentrion

You need an active Sentrion API key and an MCP client that supports **Streamable
HTTP** with a bearer token or custom `Authorization` header.

<Steps>
  <Step title="Get your API key">
    In the [Sentrion dashboard](https://app.sentrion.ai), open **Settings > API Keys**
    and create a key.
  </Step>

  <Step title="Add the MCP server">
    Add a remote server in your client's MCP settings using these values:

    | Setting | Value |
    | - | - |
    | Server name | `Sentrion` |
    | Server URL | `https://mcp.sentrion.ai/mcp` |
    | Transport | Streamable HTTP |
    | Header name | `Authorization` |
    | Header value | `Bearer YOUR_API_KEY` |

    Replace `YOUR_API_KEY` with your key. If your client has a dedicated bearer-token
    field, enter the key alone; the client adds the `Bearer` prefix.
  </Step>

  <Step title="Verify the connection">
    Ask your assistant: **"Check my Sentrion credit balance."** It should call
    `get_credit_balance`, which consumes no credits.
  </Step>
</Steps>

<Note>
  The server uses API-key authentication and does not provide an OAuth browser
  login flow. Your client must support sending a bearer token or custom header.
</Note>

<Info>
  Keep your API key private. Configure it in your client's authentication settings
  rather than including it in prompts or committing it to version control.
</Info>

## Try a search

For example, ask your assistant:

> Find 10 current engineering jobs in Amsterdam. Look up the department and
> location filter values first, then show the job titles, companies, and links.

Or, for a specific company:

> Find 10 current jobs at Google using the company LinkedIn URL
> [https://www.linkedin.com/company/google/](https://www.linkedin.com/company/google/).

When building searches:

* **Company identity:** Both company-search tools require `company_linkedin_url`.
* **Filters:** Use department and job board values exactly as returned by the
  lookup tools. For locations, pass the returned `value` objects in
  `jobs_locations` or `exclude_jobs_locations`, rather than display labels.
* **Page size:** Request 10–100 jobs per page to keep results manageable.
* **Pagination:** Pass the response's `search_after` cursor unchanged into the
  next call, keeping the same filters. Stop when no next cursor is returned.
* **History:** Every plan includes historical searches covering postings back to
  2020\. Specify the date range you want your assistant to search.

## Credits and authentication

Searches consume your account's API credits. Department, job board, location,
and credit-balance lookups consume no credits and work with zero or negative
balances.

Each HTTP request validates your API key through the credit-balance endpoint.
Tool calls use the verified key for that request, so results and billing belong
to your account. Revoked or inactive keys cannot connect. Authentication also
fails if the key-validation service is unavailable.

## Python example

With the `fastmcp` package installed, set `SENTRION_API_KEY` in your environment
and run this example to list the tools and check your balance:

```python theme={null}
import asyncio
import os

from fastmcp import Client


async def main():
    async with Client(
        "https://mcp.sentrion.ai/mcp",
        auth=os.environ["SENTRION_API_KEY"],
    ) as client:
        print(await client.list_tools())
        print(await client.call_tool("get_credit_balance"))


asyncio.run(main())
```

## Troubleshooting

| Problem | What to check |
| - | - |
| Cannot authenticate | Use an active Sentrion API key and send `Authorization: Bearer YOUR_API_KEY`. Check for whitespace or a duplicated `Bearer` prefix. |
| Client asks for an OAuth login | Configure bearer-token or custom-header authentication. OAuth login is not supported. |
| Balance works but searches fail | Check your remaining credits: new standard jobs cost one credit each and new historical jobs cost two. Historical access is included on every plan. |
| Company search fails validation | Include `company_linkedin_url`; a company name alone is insufficient. |
| Location lookup fails validation | Provide `q` with at least three non-whitespace characters. |
| Search takes too long | The adapter allows up to 180 seconds for API requests. Check your client's timeout and narrow the search filters. Requests are not retried automatically. |

API HTTP errors surface as MCP tool errors. Also inspect the search response's
`success` and `error` fields: the API can return a search failure in an HTTP 200
response. See [response formats and errors](/api-reference/introduction#response-format).


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