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

# Run a search from a coding agent

> Connect Claude Code or Codex, give the agent a brief, and check what it runs. Uses 1 shortlist credit.

> Agents: the full documentation index is at [/llms.txt](https://docs.revcenter.ai/llms.txt).

<Note>
  **Coming soon.** This recipe uses the `revcenter` CLI and MCP server, which are not published yet. Until then, the
  [quickstart](/quickstart) and the [backend job recipe](/recipes/backend-job) do the same through the API.
</Note>

A coding agent can drive Revcenter through the [MCP server](/tools/mcp) or by running the [CLI](/tools/cli).
Both call the same API, so the agent does the reasoning and Revcenter does the searching, scoring and keeping
of the shortlist. This recipe uses **1 shortlist credit**, for one search.

## 1. Connect the agent

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add revcenter --env REVCENTER_API_KEY=<your key> -- npx -y revcenter mcp
    ```
  </Tab>

  <Tab title="Codex">
    In `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.revcenter]
    command = "npx"
    args = ["-y", "revcenter", "mcp"]
    env = { REVCENTER_API_KEY = "<your key>" }
    ```
  </Tab>
</Tabs>

Keep the key in the client's configuration, never in the prompt.

## 2. Give it the brief

```text theme={null}
First read https://docs.revcenter.ai/llms.txt. Use the Revcenter tools.
Before launch_search or expand_search, tell me and wait for my OK: each uses 1 shortlist credit.
Role: Plant Maintenance Manager in Lancaster, PA.
1. Read the criteria reference and draft criteria. Show them to me.
2. After I approve, create a project, launch one search with an idempotency key, and wait for it.
3. Show me everyone scoring 80 or more, and why each fits.
4. Preview lowering the cut-off to 75 and tell me who it would add. Apply nothing without asking.
```

## 3. What the agent runs

These are the same steps as CLI commands, which is also how an agent without MCP does it. Each step's output is
what the agent reads.

```bash theme={null}
revcenter reference | jq '{fields: (.fields | length), example: (.example | keys)}'
```

```json theme={null}
{ "fields": 32, "example": ["current_industries", "geo_radius_mi", "metro", "must_have", "title_variants", "years_experience"] }
```

```bash theme={null}
PROJECT=$(revcenter project create "Plant Maintenance Manager, Lancaster PA" | jq -r .id)
echo '{"title_variants":["Plant Maintenance Manager","Maintenance Manager"],"metro":"Lancaster, PA"}' > criteria.json
revcenter search "$PROJECT" --criteria criteria.json --key "agent-$PROJECT"
```

```json theme={null}
{
  "search_id": "0b7d4a9c-…",
  "reused": false,
  "compiled_by": "caller",
  "criteria": { "metro": "Lancaster, PA", "title_variants": ["Plant Maintenance Manager", "Maintenance Manager"] },
  "database_only": false
}
```

`compiled_by: "caller"` means the search runs exactly the agent's criteria. If the agent retries with the same
`--key`, it gets `"reused": true` and the same `search_id`, and no second credit is used:

```bash theme={null}
SEARCH=$(revcenter search "$PROJECT" --criteria criteria.json --key "agent-$PROJECT" | jq -r .search_id)
revcenter search "$PROJECT" --criteria criteria.json --key "agent-$PROJECT" | jq '{reused}'
```

```json theme={null}
{ "reused": true }
```

The same key on a different request is refused, so an agent can't relaunch with new criteria by accident:

```bash theme={null}
curl -s -X POST "${REVCENTER_API_URL:-https://api.revcenter.ai}/v1/projects/$PROJECT/searches" \
  -H "Authorization: Bearer $REVCENTER_API_KEY" -H "Idempotency-Key: agent-$PROJECT" -H "Content-Type: application/json" \
  -d '{"criteria":{"title_variants":["Maintenance Supervisor"],"metro":"Lancaster, PA"}}' | jq .error
```

```json theme={null}
{
  "code": "idempotency_key_reused",
  "message": "This Idempotency-Key was already used for a different request. Use a new key for a new search."
}
```

Nothing is launched or charged. A new search needs a new key.

```bash theme={null}
revcenter status "$SEARCH" --wait | jq '{status, outcome, delivered}'
revcenter people "$SEARCH" --min-score 80 --no-profile | jq '[.people[] | {name, score, fit}]'
```

```json theme={null}
[{ "name": "Dana Whitfield", "score": 91, "fit": { "title_match": 1, "geo_fit": 1, "tier": "A" } }]
```

```bash theme={null}
revcenter rescore "$SEARCH" --cutoff 75 --preview
```

```json theme={null}
{
  "shortlistBefore": 1,
  "shortlistAfter": 2,
  "added": 1,
  "removed": 0,
  "addedExamples": [],
  "removedExamples": [],
  "before": {},
  "after": {}
}
```

A preview changes nothing and uses no credits. The numbers above are from a small example search.

## Next

* [Agents](/tools/agents) has the full workflow and good practice.
* [Errors](/guides/errors) lists the codes an agent should handle, and which calls are safe to retry.


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