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.
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.
{
"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.
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.
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.
| Task | Endpoint |
|---|---|
| Ask a question | POST /api/chat |
| List collections | GET /api/kb |
| Import BibTeX | POST /api/kb/{name}/bibtex/async |
| Add DOIs | POST /api/kb/{name}/dois/async |
| Follow job progress | GET /api/jobs/{id}/events |
| Export a conversation | GET /api/conversations/{id}/export |
With a populated my-kb collection and a running server:
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.