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

# MCP

> Connect your agent via MCP Streamable HTTP — guidelines and posting tools

Correl8 exposes a project-scoped MCP server over **Streamable HTTP**: guideline-loading tools and posting tools.

## Endpoint

```
https://api.correl8.ai/mcp/v1/project/{project_id}/
```

Project ID and MCP URL are in **Settings → Details**.

## Authentication

```
Authorization: ApiKey c8.xxx
```

Create keys in **Settings**.

## Tool: `get_correl8_guidelines`

Call once at the start of each conversation (do not re-call). Pass **`user_id`** when you have a stable end-user id.

Returns JSON:

```json theme={null}
{
  "observations": "markdown…",
  "research": "markdown…"
}
```

* **`observations`** — when and how to call **`post_observations`** (project-configurable in the app, or defaults)
* **`research`** — only included when this project has at least one **active** research study; how to conduct studies and call **`post_research_answer`**

Add the [system prompt snippet](/essentials/agent-prompt) so your agent calls this tool at conversation start.

## Tool: `get_active_studies`

Active research studies for a user. Pass **`user_id`**. Call before investigating a study, and again whenever you need the latest logged answer.

Returns JSON:

```json theme={null}
{
  "user_id": "user-42",
  "studies": [
    { "question": "…", "eligibility_criteria": "…", "answer": null }
  ]
}
```

`studies: []` when none are active for that user. Sampling, duration, and answer caps are checked server-side — **`eligibility_criteria` is not**; your agent must evaluate it against the current user/conversation before pursuing the study. Each entry's **`answer`** is the answer already logged for this user (`null` if none yet). Use an entry's **0-based index** in the `studies` array as `study_index` for `post_research_answer`.

## Tool: `post_observations`

Post one or more observations in a single call. Pass **`user_id`**, **`interaction_id`**, and **`user_sentiment`** once, then an **`observations`** array (minimum 1, maximum 50).

### Parameters

<ParamField path="user_id" type="string" required>
  Stable identifier for the end user (one per call).
</ParamField>

<ParamField path="interaction_id" type="string" required>
  Stable identifier for the conversation thread (one per call), e.g. `conv_9f3a2b1c`.
</ParamField>

<ParamField path="user_sentiment" type="string" required>
  Label for all items in the call: `very negative`, `negative`, `neutral`, `positive`, or `very positive`. See [User sentiment](/essentials/using/observations#user-sentiment).
</ParamField>

<ParamField path="observations" type="array" required>
  List of observation objects. Each item uses the fields below.
</ParamField>

<ParamField path="observations[].title" type="string" required>
  Short plain-text summary (one line).
</ParamField>

<ParamField path="observations[].description" type="string" required>
  Plain prose with context — what happened, why it mattered, and how to reproduce when relevant.
</ParamField>

### Response

Returns a list of created observations (same shape as REST `results`). On validation errors, the tool raises an error with details.

```json theme={null}
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user_id": "user-42",
    "interaction_id": "conv_9f3a2b1c",
    "title": "Enter key did not submit message",
    "description": "The user pressed Enter in the chat composer expecting the message to send. The message stayed in the input field.",
    "user_sentiment": "negative",
    "observed_at": "2026-06-10T14:30:00Z",
    "created_at": "2026-06-10T14:30:00Z",
    "tags": []
  }
]
```

## Tool: `post_research_answer`

Post a research study answer after learning what the study targets through natural conversation. Follow the **`research`** guidelines from **`get_correl8_guidelines`** and the study list from **`get_active_studies`**. Args: **`study_index`** (0-based in the `studies` array from `get_active_studies`), **`user_id`**, **`interaction_id`**, **`answer`**.

## Server-side processing

After a successful **`post_observations`** call, tag matching and issue digest run asynchronously **per observation**. See [Concepts](/essentials/concepts) for billing limits.

## Custom integration (REST API)

Same batch shape at `POST /v1/project/{project_id}/observations/` with top-level `user_id`, `interaction_id`, `user_sentiment`, and `{ "observations": [ … ] }`. Guidelines: `GET …/correl8-guidelines/?user_id=…`. Active studies: `GET …/research/studies/?user_id=…`. See [Advanced ingestion](/essentials/overview).