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

# Agent Quickstart

> Connect an AI agent to Pulse and run a reliable document workflow with MCP tools.

Use this page when an AI agent should read documents, choose the right Pulse tools, and return grounded output with minimal custom code.

## Fast Path

<Steps>
  <Step title="Create an API key">
    Open the [Pulse Platform](https://platform.runpulse.com), create an API key, and keep it out of source control.
  </Step>

  <Step title="Connect an MCP client">
    Use the hosted server for URL-based documents. Use the local server when the agent must read files from disk.
  </Step>

  <Step title="Give the agent a document">
    Hosted MCP needs a public or pre-signed `file_url`. Local MCP can use either `file_url` or an absolute `file_path`.
  </Step>

  <Step title="Run extract first">
    Most workflows start with `extract`. Use the returned `extraction_id` for schema, split, and table tools.
  </Step>

  <Step title="Poll when needed">
    If any tool returns `{ "status": "processing", "job_id": "..." }`, call `get_job` until the job completes.
  </Step>
</Steps>

## Client Configs

<Tabs>
  <Tab title="Codex Hosted">
    ```toml ~/.codex/config.toml theme={null}
    [mcp_servers.pulse]
    url = "https://mcp.runpulse.com/mcp"
    http_headers = { "x-api-key" = "YOUR_PULSE_API_KEY" }
    ```
  </Tab>

  <Tab title="Claude Code Hosted">
    ```bash theme={null}
    claude mcp add --transport http pulse https://mcp.runpulse.com/mcp \
      --header "x-api-key: YOUR_PULSE_API_KEY"
    ```
  </Tab>

  <Tab title="Local">
    ```toml theme={null}
    [mcp_servers.pulse]
    command = "uvx"
    args = ["pulse-mcp@latest"]
    env = { "PULSE_API_KEY" = "YOUR_PULSE_API_KEY" }
    ```
  </Tab>
</Tabs>

See [Connecting a client](/mcp/connecting) for Claude Desktop, VS Code, and more setup options.

## First Agent Prompt

Give the agent the document location, the output you want, and any evidence requirements:

```text theme={null}
Use Pulse to extract this document:
https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf

Return account holder, statement period, ending balance, and all transactions as JSON.
Include citations or source references for each field when available. If the extraction
is still processing, poll with get_job until it is complete.
```

For long or mixed documents, be explicit about the plan:

```text theme={null}
Use Pulse on this filing. First extract it with page chunking. Then split it into
sections for procedural history, allegations, arguments, and requested relief.
Apply a separate schema to each split section and return the result as JSON with page
references.
```

## Tool Paths

| Agent goal                 | Tool path                                        | Notes                                                             |
| -------------------------- | ------------------------------------------------ | ----------------------------------------------------------------- |
| Parse a document into text | `extract`                                        | Start here. Returns markdown and `extraction_id`.                 |
| Get structured JSON        | `extract` -> `generate_schema` -> `apply_schema` | Use `generate_schema` when the agent needs help designing fields. |
| Run a known schema         | `extract` -> `apply_schema`                      | Pass the schema directly or use a saved `schema_config_id`.       |
| Route a long packet        | `extract` -> `split_document` -> `apply_schema`  | Use when different pages need different schemas.                  |
| Pull tables                | `extract` -> `extract_tables`                    | Turn on table merge for cross-page tables.                        |
| Process many URLs          | `batch_extract` -> `get_job`                     | Use for asynchronous batches.                                     |
| Run a saved workflow       | `run_pipeline` -> `get_job`                      | Best when product teams already maintain a Platform pipeline.     |

## Extraction Settings Agents Should Know

Agents can pass the same high-impact extraction settings you use in the Platform:

| Setting                               | Use when                                            |
| ------------------------------------- | --------------------------------------------------- |
| `pages`                               | The user only needs specific pages.                 |
| `footnote_references`                 | Footnote markers and body text need to be linked.   |
| `figure_descriptions`                 | Charts, images, or diagrams need text descriptions. |
| `show_images`                         | The app needs image URLs for extracted visuals.     |
| `chunk_types` and `chunk_size`        | Output will feed retrieval, memory, or embeddings.  |
| `only_data_rows` and `only_data_cols` | Excel files have large empty trailing ranges.       |

For the broader Platform/API view of these settings, see [Processing Parameters](/concepts/processing-parameters).

## Agent Guardrails

* Hosted MCP cannot read local disk paths. Use a public or pre-signed URL.
* Local MCP can read an absolute `file_path`, but chat attachments are not automatically file paths.
* Always reuse `extraction_id` instead of re-extracting the same document.
* Poll `get_job` before passing a result into the next tool.
* Ask for a schema before writing JSON to a database or downstream system.
* Keep API keys out of prompts, logs, screenshots, and committed config.
* For regulated workflows, return page references, footnote links, chunks, or bounding boxes whenever users need evidence.

<CardGroup cols={2}>
  <Card title="MCP Tools" icon="wrench" href="/mcp/tools">
    Full tool parameters and return shapes.
  </Card>

  <Card title="Sample Documents" icon="file-pdf" href="/cookbooks/sample-documents">
    Public documents agents can use for smoke tests.
  </Card>
</CardGroup>