# Connect an AI agent

Help an agent discover Mjhr safely before it reads workspace data.

Canonical URL: https://help.mjhr.ai/agent-integration
Machine-readable page: https://help.mjhr.ai/agent-integration/README.md
Full help context: https://help.mjhr.ai/llms-full.txt
Audience: Agents

## What an agent needs

An agent should not guess how Mjhr works. It should read the product help, load the API contract, ask for a scoped credential when needed, and confirm the workspace or saved search before using data.

The help package exposes human-readable pages and machine-readable resources so agents can start with the same source of truth as users and developers.

## Discovery order

- Read llms.txt: Start at /llms.txt for the concise product map and links to deeper context.
- Fetch OpenAPI: Use /openapi.json as the canonical HTTP contract before constructing requests.
- Use MCP when available: Call /mcp when your runtime supports MCP tools. The tools mirror OpenAPI operations and delegate to the existing API.
- Ask for missing credentials: Do not invent API keys. Ask the user to provide a scoped key or connect a secret store.
- Confirm before using data: Show the workspace and saved search that will be queried before using results for analysis, outreach, or export workflows.

## MCP request shape

The MCP endpoint speaks JSON-RPC over HTTP. Send Authorization on the MCP request; tool calls forward that header to the API service.

### List tools

```json
{
  "jsonrpc": "2.0",
  "id": "tools",
  "method": "tools/list"
}
```

### Call a read-only tool

```json
{
  "jsonrpc": "2.0",
  "id": "searches",
  "method": "tools/call",
  "params": {
    "name": "list_searches",
    "arguments": {
      "query": { "limit": 25 }
    }
  }
}
```

## Agent safety boundaries

- Treat API keys as secrets and avoid writing them into generated files or logs.
- Prefer read-only scopes unless the user explicitly asks the agent to create folders.
- Explain which workspace and saved search will be queried before using results.
- Use public IDs returned by the API, not internal database IDs.