AI agents
How do AI agents use RolesAPI?
RolesAPI ships a hosted MCP (Model Context Protocol) server, so agents like Claude can search Indeed job postings and pull role details as native tool calls — no glue code.
https://api.rolesapi.com/mcpTransport is streamable HTTP. Authentication is either OAuth 2.1 with PKCE (the agent walks the user through sign-in) or a plain Bearer rk_ API key. Tool calls consume credits from the connected account exactly like REST calls — 1 credit per role detail or search page.
What tools does the MCP server expose?
| Tool | What it does |
|---|---|
search_roles | Search postings by keyword and location; returns a page of role summaries. |
get_role_by_key | Fetch a full role object by its Indeed job key. |
get_role_by_url | Fetch a full role object from an Indeed viewjob URL. |
get_salary_info | Return just the salary block for a role. |
get_role_description | Return just the full description text for a role. |
Example tool-call arguments:
{ "tool": "search_roles", "arguments": { "keyword": "backend engineer", "location": "Austin, TX", "country": "us", "sort": "date" } }{ "tool": "get_role_by_key", "arguments": { "job_key": "a1b2c3d4e5f60718", "country": "us" } }{ "tool": "get_role_by_url", "arguments": { "url": "https://www.indeed.com/viewjob?jk=a1b2c3d4e5f60718" } }{ "tool": "get_salary_info", "arguments": { "job_key": "a1b2c3d4e5f60718", "country": "us" } }{ "tool": "get_role_description", "arguments": { "job_key": "a1b2c3d4e5f60718", "country": "us" } }How do I connect Claude Code?
claude mcp add --transport http rolesapi https://api.rolesapi.com/mcpHow do I connect Claude Desktop?
Add to claude_desktop_config.json:
{"mcpServers":{"rolesapi":{"command":"npx","args":["mcp-remote","https://api.rolesapi.com/mcp"]}}}How do I connect Cursor?
Add to .cursor/mcp.json:
{"mcpServers":{"rolesapi":{"url":"https://api.rolesapi.com/mcp"}}}On first use, each client either opens the OAuth sign-in flow or accepts a Bearer rk_ key, depending on how you configure credentials.
What machine-readable surfaces exist?
For agents and tooling that discover capabilities by convention:
| Surface | Path |
|---|---|
| OpenAPI specification | https://api.rolesapi.com/openapi.json |
| LLM-oriented index | https://rolesapi.com/llms.txt |
| Full LLM context file | https://rolesapi.com/llms-full.txt |
| MCP server card | https://api.rolesapi.com/.well-known/mcp/server-card.json |
| API catalog | https://api.rolesapi.com/.well-known/api-catalog |
| Agent skills | https://rolesapi.com/agent-skills |
Point a coding agent at llms-full.txt and it can write a working integration without browsing these docs.
When should an agent use REST instead of MCP?
MCP tools cover interactive lookups — one role, one search, one salary check. For bulk workloads (a 500-role batch, a search with full details), the REST async jobs surface is the better fit; an agent can submit the job, then poll GET /v1/jobs/{id} with ordinary HTTP calls.