Skip to content

docs(mcp): document find_threads and existing thread tools (CON-5231) #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
devin-ai-integration wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs(mcp): document find_threads and existing thread tools (CON-5231) #13

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions consensus-mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -302,6 +302,68 @@ Each search returns:
- "Recent research on large language model hallucination from top tier journals"
- "Use Consensus Deep Research to compare evidence for different treatments for insomnia"

## Research thread tools

If your Consensus account has thread tools enabled, you can use the research thread tools below. They require a signed-in OAuth session; API-key and anonymous callers cannot use them.

### create_thread

Start a new research thread and dispatch the Consensus research agent. Use this for detailed, citation, synthesis, comparison, contradiction, literature-review, or multi-step research questions. For a simple list of papers, use `search` instead.

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| input_message | string | Yes | The complete research brief. Include the question, scope, constraints, and any ordered sub-tasks. |
| mode | string | No | Research depth. `pro` (default, ~20 papers, fast) or `deep` (~50 papers, up to 10 minutes, requires a paid account). |
| filters | object | No | Same structured filters as `search`. |
| attachments | object | No | Optional `paper_attachments` or `collection_ids` to scope the research. |

#### Response

Returns a dispatch confirmation with `thread_id`, `interaction_id`, `title`, `status` (`running`), `mode`, and a `url` to view the thread on Consensus.

### add_to_thread

Add a new interaction to an existing research thread. Use this only for a genuine follow-up after you see the previous interaction's results.

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| thread_id | string | Yes | The `thread_id` returned by `create_thread`. |
| input_message | string | Yes | A new follow-up question. |
| mode | string | No | `pro` (default) or `deep`. |
| title | string | No | The thread title, used only for the deep-link label. |
| filters | object | No | Same structured filters as `search`. |
| attachments | object | No | Same as `create_thread`. |

#### Response

Returns a dispatch confirmation with the new `interaction_id`, `thread_id`, `status` (`running`), `mode`, and `url`.

### find_threads

List your research threads. This is useful for finding or resuming a previous conversation.

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| query | string | No | Optional title substring search. Leave empty to list all threads. |
| limit | integer | No | Maximum threads to return. Default `20`, minimum `1`, maximum `100`. |
| offset | integer | No | Pagination offset. Default `0`. |

#### Response

<ResponseField name="threads" type="array">
Array of thread objects, each with `thread_id`, `title`, `status` (`idle`, `running`, `failed`, or `unknown`), `preview`, `interaction_count`, `last_activity_at`, and `url`.
</ResponseField>

<ResponseField name="has_more" type="boolean">
`true` when more results are available.
</ResponseField>

## Troubleshooting

<AccordionGroup>
Expand Down