Connect an AI agent (MCP) and the API

What you get

• Hikma Research exposes one MCP server (Model Context Protocol, streamable HTTP). Any MCP-capable agent — a coding assistant in your terminal, a desktop assistant, an IDE — reaches your projects with it: search the literature and add works, fetch full texts and read them page by page or as structured XML, read the evidence table, plan and record screening, save risk-of-bias and GRADE judgements, run meta-analyses and analysis plans, write and edit manuscript text as tracked changes, run the checks, list projects and tasks. This is how AI works on this platform by default: your client does the reasoning, Hikma holds the research.
• The agent acts as you: exactly your permissions in exactly your projects, every action logged under your account on the project’s Activity tab. The same guard-rails apply — it cannot cite a work outside the project library or type an unsourced number into a manuscript, and its edits arrive as tracked changes for you to accept.
• Your server address is shown under Settings → Integrations (it ends in /mcp). On a personal machine it is http://localhost:4100/mcp; on a deployment it is your API's public HTTPS address plus /mcp.

Your subscription, not ours

Connecting your own agent needs no Hikma subscription and no card: a free account and a personal key (or an OAuth sign-in from the client) are enough. Your agent's reasoning is billed by its own provider exactly as it is today; everything it does through Hikma — searching nine bibliographic sources, fetching full texts, reading and extracting evidence, writing manuscripts as tracked changes, screening, pooling, analysing data — is free.

• Bring-your-own-agent mode (the default). The platform spends no model keys, so the tools that would have done the thinking are not offered — and each names the contract that takes your agent's judgement instead. Your agent reads sources with read_source_page, read_source_xml and search_source_text, reasons itself, and hands in what it concluded: submit_evidence_units (the server checks each quote against the page and decides verified / partial / unverified / contradicted / not_reported), propose_section (the server binds the numbers and reports every digit that bound to nothing), submit_screening_votes, propose_risk_of_bias, propose_grade, submit_claim_dispositions, submit_critique_findings, submit_readiness_assessment, submit_source_summary and submit_search_plan. Nothing is metered by Hikma.
• Platform AI mode. An administrator may additionally switch on Hikma's own assistant (Admin → AI & keys). Then tools such as draft_section, gather_evidence, verify_claims, critique_manuscript and screen_works also appear over MCP; they run on the platform's keys and count against the project's monthly budget, never against you personally while billing is off. The submission contracts stay available in both modes — an agent that read the papers itself should be able to say so.
• Either way the agent sees exactly your projects with exactly your role, and every call is recorded as a conversation in the project's Your AI tab.

The easy way: from the Your AI tab

Open a project → Your AI. A project without conversations shows the Connect panel first; afterwards the Connect your AI button above the conversations opens the same steps. Choose your client, which tools it gets, and how it signs in; the panel shows the exact command or configuration with the server address (and your new key, if you chose one) filled in, then confirms the connection when the first call arrives. What the agent does then appears as a conversation in that project, and the manuscripts it writes open beside the chat.

• Toolsets. Everything is the default (188 tools when the administrator has switched platform AI on; 176 in bring-your-own mode, where the model-backed ones are replaced by the submission contracts). Literature & writing (about half the schema size), Systematic review and Data analysis are smaller packs for clients that struggle with many tools; a key remembers the pack you chose, and any client can ask for a pack with the header X-Hikma-Tools: writing | review | data | all (Claude Code: --header).
• Online. The address shown is your deployment's public API address (https://api.hikmaresearch.org/mcp on the production platform). Hosted clients — Claude Desktop, claude.ai, ChatGPT — sign in through OAuth against it; local development servers are only reachable from clients on the same machine.

Two ways to authenticate

• OAuth (recommended for people): add the server by URL; the client opens your browser, you sign in and approve the client, and it receives tokens bound to your account. Revoke a client any time under Settings → Integrations → Connected clients.
• API key (for scripts, servers and clients without OAuth): Settings → Integrations → New key (choose an expiry of 30–365 days), then send it as an Authorization: Bearer header. Keys are limited to 600 requests per minute and can be revoked at once; treat them like passwords and never commit them.
• Clients that only speak stdio (no HTTP) reach the server through the mcp-remote bridge: npx -y mcp-remote <server-url> — add --header "Authorization: Bearer <KEY>" for a key, or let it run the OAuth flow.

Claude Code (terminal)

bash

Then ask in plain language: “List my projects”, “Search PubMed and OpenAlex for prophylactic amiodarone after cardiac surgery and add the ten most relevant trials to project X”, “Extract the evidence table from the included works”, “Draft the Background from the evidence and propose it as tracked changes”. The research_method prompt on the server explains the evidence-first rules to the agent; run it once per session.

Claude Desktop and claude.ai

• Settings → Connectors → Add custom connector → paste your server address (a public HTTPS address is required; localhost is not reachable from the hosted app) → Add → sign in and approve when the browser opens.
• Enable the connector in a chat with the tools icon. Everything you ask runs under your account; disable or remove the connector from the same screen.
• Claude Desktop also accepts a JSON configuration with the mcp-remote bridge for local development: see the generic section below.

OpenAI Codex

toml

Recent Codex CLI versions also accept the command line: codex mcp add hikma --url https://api.hikmaresearch.org/mcp. Check codex mcp list, then ask Codex to call the Hikma tools like any other MCP server.

Cursor, Windsurf, VS Code, Zed, Cline and others

json

Each client shows the Hikma tools in its tools list after the first successful call. The exact file names and keys follow each client's current release; the shapes above are the ones in use at the time of writing — when in doubt, the client's own MCP documentation wins, and the server address never changes.

ChatGPT

In ChatGPT, Settings → Connectors (developer mode must be enabled by your workspace) → Create → paste the server address → connect with OAuth. A public HTTPS address is required.

What the agent can call

Tool names as listed by the server are authoritative (ask the agent to list them). Articles are fetched as structured XML whenever a source offers it: fetch_article takes a DOI, PubMed id, PMCID, arXiv id or URL, walks the open-access ladder (Europe PMC / PubMed Central, Europe PMC preprints, bioRxiv/medRxiv, PLOS, Frontiers, PeerJ, MDPI, Copernicus, then PDFs through GROBID), waits for parsing and returns the section map; read_source_xml serves the JATS or TEI markup in slices for agents that prefer it to page text.

Long-running tools do not block the client: acquire_full_text, extract_evidence and summarize_sources return a job at once, and over MCP so do draft_section, gather_evidence, verify_claims, critique_manuscript and check_evidence_readiness (their model calls can outlast a client's 60-second request limit). The agent polls get_job with waitSeconds up to 45 and reads the tool's result there; the outcome lands in the project like any other action.

Tool names as listed by the server are authoritative (ask the agent to list them). Long-running tools return a job that the agent polls; results land in the project like any other action.

Security

• Every request is authenticated — an OAuth access token bound to your account and the approved client, or an API key (hashed at rest, shown once, 90-day expiry by default, revocable, last use visible under Settings → Integrations). Unauthenticated calls get 401; the whole API is rate-limited per address.
• Authorisation is per project. Each tool checks your role in the project it touches (viewer, editor, owner); an agent using your key sees exactly what you see, and calls on projects you do not belong to are refused before anything is recorded.
• Inputs are validated (typed schemas on every tool) and all database access is parameterised. Uploads are checked for type and size and stored content-addressed.
• Prompt injection. Text coming back from documents and databases is marked as data in every reading tool's result, and the server's instructions tell the agent never to follow instructions found in sources. Messages an agent posts are rendered as plain text and Markdown, never as HTML.
• Outbound fetches are guarded. When Hikma downloads a paper it only follows public http(s) addresses; private, loopback, link-local and cloud-metadata destinations are refused at every redirect hop, and DNS answers are checked.
• Recording is scoped. MCP conversations are created only in projects you belong to, under your user, and inherit the project's budget; long tools run as jobs you can only read back yourself.
• Online. Publish the API over HTTPS behind your domain; hosted clients (Claude Desktop, claude.ai, ChatGPT) need that public address. Keep the OpenAlex key and other provider keys in the admin key store — never in a client configuration.

Troubleshooting

• 401 or “unauthorized” — the token expired or the client was revoked: in Claude Code run /mcp and authenticate again; in other clients remove and re-add the server, or create a fresh API key.
• The hosted Claude or ChatGPT cannot reach localhost: use your deployment's public HTTPS address, or test with Claude Code, Codex or an IDE on the same machine.
• 429 — an API key is capped at 600 requests per minute; unattended loops should pace themselves.
• The agent proposes edits you cannot see — open the manuscript: proposals appear as tracked changes in the Changes panel; nothing is applied silently.
• Ask the agent to run the research_method prompt first if it starts inventing citations; the rules stop it from doing so through the tools regardless.