CNRS·Université Côte d'Azur·Institut de Chimie de Nice·Centre Inria de l'Université Côte d'Azur·Interdisciplinary Institute for Artificial Intelligence (3iA) Côte d'Azur
HolobiomicsLab

MCP, REST, and the command line

Give your agent a literature workspace

Connect to your local Perspicacité server to discover papers, search collections, retrieve passages, and generate research reports from the same knowledge bases you use in the web interface.

A local research service

One endpoint for your MCP client.

The MCP server is served at http://localhost:8000/mcp over streamable HTTP. Start the Perspicacité backend first. The supplied config.example.yml binds to the loopback address 127.0.0.1 on port 8000; use the port from your own configuration if you change it.

Terminal
uv run perspicacite -c config.yml serve

The repository names Claude Code, Codex, Mimosa-AI, SmolAgents and Cursor as clients. Each connects to the same endpoint; use the client's HTTP MCP configuration rather than launching a second Perspicacité process for every tool call.

There is no authentication on the MCP endpoint by default. Keep it on localhost, or put it behind a reverse proxy that authenticates requests.

Claude Code

Add this server entry to your MCP configuration. It follows the repository's example, with the port set to the default of the current example configuration.

JSON configuration
{
  "mcpServers": {
    "perspicacite": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Other clients

For Codex, Mimosa-AI, SmolAgents, Cursor or another compatible client, enter the same URL and select an HTTP (streamable) transport in its MCP connection settings. The exact steps depend on the client; consult its documentation.

A useful first agent workflow

Inspect, retrieve, then synthesize.

Find the collection

Use list_knowledge_bases to inspect the available collections. Select one explicitly, or use route_kbs to see which collections match the question.

Look at the evidence

Use search_knowledge_base or get_relevant_passages to retrieve evidence. If the collection is missing relevant papers, discover candidates and ingest the ones the workflow needs.

Ask for a report

Use generate_report with an appropriate mode. Start with basic or advanced, inspect the sources, and add broader discovery or deeper analysis only when useful.

Report mode values are basic, advanced, deep_research, agentic, literature_survey and contradiction. profound remains accepted as a deprecated alias for deep_research.

Allow longer client timeouts for live discovery and report generation than for a local knowledge-base lookup: the project's guide budgets 15 to 50 seconds for a multi-database search, under a second for a knowledge-base search, and 30 to 120 seconds for a report, and recommends a client timeout of at least 60 seconds.

Response contract and latency guidance ↗

Tool inventory

Discover, organize, retrieve, preserve.

The server registers 55 tools, listed with their purpose on the MCP tools page. Registration does not guarantee availability: a tool can depend on configuration, optional dependencies and external services. Multi-database search needs the SciLEx integration, Zotero operations need a Zotero library configuration, and claim-graph tools need integrations that a fresh public installation does not include.

Browse the catalogue →

For applications and scripts

Use the JSON API directly.

The FastAPI backend also exposes REST endpoints. Asynchronous ingestion returns a job identifier, with server-sent events for progress; chat can stream its response.

Selected REST endpoints
TaskEndpoint
Ask a questionPOST /api/chat
List collectionsGET /api/kb
Import BibTeXPOST /api/kb/{name}/bibtex/async
Add DOIsPOST /api/kb/{name}/dois/async
Follow job progressGET /api/jobs/{id}/events
Export a conversationGET /api/conversations/{id}/export

With a populated my-kb collection and a running server:

Terminal
curl -sN -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"query":"What methods are used in these papers?","kb_name":"my-kb","mode":"basic","stream":true}'

For client code, consult the repository's endpoint and error contracts. The REST API can require a bearer token; the reference describes when. These examples assume the local installation described above.

Full REST API reference ↗