How to connect Elicit MCP with Python

Search Elicit's academic paper corpus. Pass `corpus` (`elicit` — default, full paper index — or `pubmed` for PubMed-only), `searchMode: "keyword"` to interpret the query as a Lucene-style expression instead of natural language, or `filters` (year range, study type, journal quartile, etc.) to narrow results. For clinical trials, use `search_trials` instead.

Search for clinical trials. Trial records come from ClinicalTrials.gov. Pass `trialFilters` to narrow by phase, recruitment status, or whether the trial has posted results, or `searchMode: "keyword"` to send a Lucene-style expression directly to the underlying advanced-filter API.

Create an Elicit report for a research question.

Fetch a report by its `sessionId`. The response includes title, summary, status, and available PDF/DOCX and txt/bib/ris reference-list download URLs. For reference-list exports, `exportsStatus: ready` means a cached manifest was served, which can be stale; `generating` or `unavailable` means no cached downloads can be served. If expected reference-list URLs are missing, repoll after at least 60 seconds with bounded backoff even after completion. To also include the full report markdown and abstract, pass `includeReportBody: true`.

Create a systematic literature review with configurable search, screening, extraction, and report stages. Two options are the person's to choose, not yours: screening `depth` and `extraction.useFigures`, which require higher usage when enabled. Set them only from an explicit instruction, and ask the person which they want if they have not said. Tell them the settings you are about to use before calling this, and repeat the `settings` block from the response back to them. A running review cannot be amended.

Fetch a systematic review by its `sessionId`. The response includes status, available search/screen/fulltext/extract exports as CSV + XLSX under `data`, and report content and downloads when available. `exportsStatus: ready` means a cached manifest was served, not that it is current or complete; stale fallbacks can omit newly completed stages. If expected URLs are missing, repoll after at least 60 seconds with bounded backoff even after completion; `dataFreshness` helps detect an unchanged cache but is not a completeness guarantee. `generating` or `unavailable` means no cached downloads can be served. To include the full report markdown and abstract, pass `includeReportBody: true`.

List accessible research sessions — reports, systematic reviews, and Research Agent sessions — newest first. Use `type: agent` to find agent sessions, including read-only shares (`role: shared`); a share does not permit messages, stop, or resume. Each item carries a `type` and `sessionId` for the matching get tool. Filter with `type`, `status`, or `source` (including `mcp`), and paginate with `nextCursor` as `cursor`.

Resume an owned report, systematic review, or Research Agent session with status `pausedForInsufficientQuota`. Pass the `sessionId` from the create tools or `list_sessions`; the type is resolved automatically. Check `get_usage` and replenish quota before retrying `insufficient_quota`. For agents, continue polling get_agent_session_events with the saved cursor after resuming. A stopped or idle session is not quota-paused; use send_agent_session_message for a new turn instead.

Get the current account's usage status for this billing period: whether usage remains (`hasUsageRemaining`), the percentage of plan usage consumed (`percentUsed`), the billing period bounds (`periodStart`/`periodEnd`, when monthly limits reset), and — only when extra usage is enabled — extra-usage spend and limit in USD cents (`extraUsage`). Call this when a session is `pausedForInsufficientQuota` or `resume_session` returns `insufficient_quota` to check remaining headroom.

Returns your own sources, newest first. To list a shared collection's papers, pass its id in the `collectionId` query parameter; those papers are not included in the unfiltered list. Each returned source carries your `role` and its visible collection memberships in `collectionIds`. Filters combine with AND. `q` matches each term as a case-insensitive substring of the title, authors, abstract, venue, or Elicit id. A DOI-shaped term matches the DOI. `doi` and `elicitId` are exact filters. `fullTextStatus` filters by whether parsed full text is attached. Default page size 50, maximum 100. `totalCount` counts all matches, not the page.

Retrieves a source by id. `fullTextStatus` values: `pending`, Elicit has not finished looking for a PDF; `available`, full text is ready; `unavailable`, no PDF was found.

Returns the parsed full text of the source's PDF as markdown: title, abstract, and body. A `404` has one of three codes. `full_text_pending`: the PDF search or parse is in progress; retry later. `full_text_unavailable`: no PDF was found. `not_found`: the source is not visible to you.

Saves 1–100 papers. Each item is one of: an `elicitId`; a `pdfUrls` entry, metadata optional; or a `title` with at least one of `doi`, `authors`, `year`, `venue`, `abstract`, `url`. A `doi` alone is rejected. Elicit fills missing metadata from its corpus or the parsed PDF. `pdfUrls` is how to attach a PDF: Elicit fetches and parses it in the background when the paper is not in the corpus. Do not download PDFs yourself; for local files, use imports. The response lists each item in request order. An item that matches a paper already in your library returns that source with `created: false` and `duplicateOf` set. With `onDuplicate: skip` (default), fields the existing source lacked are filled from the item and listed in `updatedFields`. Existing values do not change. Adding `pdfUrls`, `doi`, or `elicitId` to an existing source starts enrichment for it again. With `onDuplicate: create`, a copy is saved and the pair is recorded as a potential duplicate. `collectionIds` adds every returned source to those collections; each source's `collections` reports, per collection, the id the collection holds for the paper and whether this call added it. A group collection holds its own copy under a different id, so the returned source's `collectionIds` does not list it. Metadata and full text for new sources arrive asynchronously. A new source starts with `fullTextStatus: pending`. When `fullTextStatus` changes, enrichment is complete. A source that still has `title: null` at that point has an identifier that is not in the corpus.

Returns the collections you own and the collections shared with you, sorted by name with id as a tie-breaker. `role` is your access level. `sharedVia` is set on collections shared with you. `links.sources` lists the sources in the collection. Send `nextCursor` as `cursor` to get the next page. Pagination is not a snapshot: renaming a collection can move it between pages, and deleting or losing access to the cursor's collection returns `400 invalid_request`. Restart from the first page if the cursor is no longer valid.

Retrieves a collection by id. `role` is your access level.

Creates an empty collection. Names are not unique. Store the returned id.

Adds up to 500 of your sources to a collection you own or can edit. `addedCount` is the number added. A source is skipped if it is already in the collection, or if a paper in the collection is the same paper. Papers match by Elicit id, DOI, title, or identical PDF. Each skipped source appears in `duplicates` with `duplicateOf`, the id of the paper already in the collection (its own id when it was already a member). Each added source appears in `added` with `collectionSourceId`, the id the collection holds for it: in a group collection the collection gets its own copy of each added source, under its own id, and your source stays yours. If any id is not a source you own, the request returns `404` and adds nothing.

Stages a local PDF for `import_library_files`. Send the filename, `content_type: application/pdf`, and the exact `size_bytes`. Then PUT the file bytes to the returned `upload_url`, for example `curl -X PUT -T paper.pdf -H 'Content-Type: application/pdf' '<upload_url>'`. Do not send an Authorization header on the PUT. Pass the returned `file_id` to `import_library_files`. A file id can be imported once. The URL expires at `expires_at`. For a PDF at a public URL, use `save_library_sources` with `pdfUrls` instead.

Imports PDFs staged with `stage_library_upload` into the user's library. Elicit parses each file, extracts its metadata, attaches the full text, and checks for duplicates. The response is an import with `status: processing` and every file `pending`. Poll it with `get_library_import` until `status` is `completed`. `collectionId` adds each imported paper to a collection, duplicates included. A file id can be imported once. A byte-identical copy of a PDF in the library is always a `duplicate`.

Retrieves an import. `status` is `processing` or `completed`. `completed` does not mean that every file succeeded. File `status` values: `pending`; `created`, with `sourceId`; `duplicate`, with `duplicateOf`; `failed`, with `error`. `error.code` values: `invalid-file`, do not retry; `processing-error` and `server-error`, a retry may succeed; `unknown`.

Start asynchronous Research Agent work from a query and optional attachments: [{file_id}] from stage_file_upload, after the bytes have been uploaded. Optionally select researchDepth: fastest, fast, balanced, smart, or smartest; omission keeps the existing account/model default. Plan and contract limits still apply, reducing unavailable depths to the allowed ceiling (smartest becomes smart on Pro). Custom model configuration is not supported. Returns a stable sessionId and an Elicit URL. Save both, then poll get_agent_session_events for progress and answers. Creation consumes account usage; do not blindly retry after a timeout—check list_sessions first to avoid duplicate work.

Inspect an owned or explicitly shared Research Agent session. Status is processing (working), completed (idle and ready for input, not permanently closed), failed, or pausedForInsufficientQuota. A stopped turn is identified by session_stopped in get_agent_session_events, not a distinct detail status. Use that tool to read the conversation and answers. Shared access is read-only.

Read conversation, research progress, answers with citations, and Methods from an owned or explicitly shared session. Omit cursor once for full history, then pass each returned cursor unchanged to receive only later events. Save a cursor only after consuming its page; retry the previous cursor after interruption and deduplicate by eventId. Later snapshots of the same messageId replace earlier snapshots for display. Poll with a delay (e.g. 5 seconds), not a tight loop; an empty page does not mean work finished. completed/session_idle means ready for a follow-up; session_stopped acknowledges a stop.

Send a follow-up to an owned Research Agent session, preferably when completed (idle) or stopped. Optionally attach uploaded files with attachments: [{file_id}] from stage_file_upload. Returns a messageId to match the user_message event for this turn; continue polling with the saved cursor. Failed sessions cannot continue; quota-paused sessions must be resumed first. Shares are read-only. Messages are not idempotent: after a timeout, inspect events before retrying.

Safely stop an owned Research Agent session, even when quota is exhausted. Repeated stop requests are safe. stopping means the stop was queued, not yet complete: poll events for session_stopped. Already stopped or failed sessions return their current state. Shared read access does not grant permission to stop.

Prepare an upload (maximum 30 MiB) for Research Agent. Supply filename, content_type, and exact size_bytes. This does not transfer the bytes: PUT the file to upload_url with matching Content-Type and Content-Length, without an Authorization header. Then pass attachments: [{file_id}] to create_agent_session or send_agent_session_message. The URL and unclaimed file_id expire at expires_at (30 minutes). A file can belong to only one session or library import; it may be reused within that session. A client without file/HTTP transfer support cannot complete an upload; do not claim it succeeded. Existing upload eligibility and file limits apply.

Discover the latest file-backed artifacts and delivered outputs in an owned or explicitly shared Research Agent session. Use the opaque artifactId unchanged: artifacts use download_agent_session_artifact with format original; deliveredOutputs use get_agent_session_artifact_content or download_agent_session_artifact with json, csv/xlsx (tables), or md (prose). delivery inline includes data; delivery download supplies the complete JSON as a short-lived URL when too large for MCP. Nothing is truncated. Do not assume a client has fetched the download.

Read a delivered output from an owned or explicitly shared session as structured JSON, including resolved citations. Use a deliveredOutputs artifactId from get_agent_session_artifacts. delivery inline includes the complete data; delivery download provides the complete JSON file and sizeBytes instead when too large for MCP. Fetch that URL outside model context and inspect it selectively; content is never silently truncated. Links expire after 30 minutes; call again for a fresh link. File-backed artifacts instead use download_agent_session_artifact.

Get a short-lived download URL for an owned or explicitly shared session artifact. Use format original (default) for file-backed artifacts; for deliveredOutputs choose json (all kinds), csv/xlsx (tables), or md (prose). Uses Elicit's existing export formats; unsupported kind/format combinations fail explicitly. Download outside model context without an Authorization header. Links are bearer capabilities valid for 30 minutes: keep them private, refresh by calling again, and use create_session_share rather than distributing a download URL. Revoking a share does not invalidate URLs already issued before their expiry.

Share an owned Research Agent session, report, or systematic review read-only with the requested email. May send an invitation email and exposes session content to the recipient: obtain the user's approval of the recipient before calling. Existing editor/reviewer grants are preserved, not downgraded. Shared recipients cannot re-share or control Research Agent sessions. This does not make the session public. Existing recipient limits and invite eligibility apply.

List read-only recipients and pending read-only invitations on an owned Research Agent session, report, or systematic review. Owner only; recipients cannot list collaborators. Existing editor/reviewer grants are omitted and must be inspected in the web app.

Revoke an email's direct share or pending invitation on an owned Research Agent session, report, or systematic review. Owner only and safe to repeat. Destructive: removes any direct role, including editor/reviewer access omitted from list_session_shares. Confirm the recipient with the user. Other access paths are unaffected; already-issued download URLs remain usable until expiry.