OpenCited

OpenCited answers questions from authoritative public sources. Every number in an answer links to the data it came from, calculations run in code where they can be checked, and the agent refuses to answer when it cannot back a number. The first source is Statistics Norway (SSB).

Note

OpenCited is in early development. The MCP server for StatBank is on PyPI as opencited. The calculation engine, the evidence gate, the agent and the evaluation suite are built. In the published runs of release 0.1.0 with DeepSeek's deepseek-flash, the agent answered 38 of 44 questions of set v1 and 39 of 43 of set v3 correctly. Of the 55 answers it released, 53 were correct, and it refused all 24 questions that it should refuse. See the roadmap.

How it works

flowchart LR
    Q[Question] --> A[Agent]
    A -- tool calls --> M[MCP server]
    M --> S[(Source APIs)]
    A --> C[Calculation engine]
    A --> G{Evidence gate}
    G -- every number backed --> R[Answer with citations]
    G -- unbacked number --> X[Retry or refusal]

Loading

1. You ask a question in Norwegian or English.
2. The agent finds the right tables through the OpenCited MCP server. Every value it gets back carries a provenance record: source, licence, table, API request, retrieval time and a hash of the raw response.
3. Calculations run as typed plans over stored snapshots, with exact arithmetic. DuckDB selects the values, and every step is shown. The language model never states a number from its own knowledge.
4. Before an answer is released, an evidence gate matches every number in it to a source value or a calculation result. An answer that fails is retried or refused with a reason.
5. An open evaluation suite measures how often the answers are right.

Installation

OpenCited needs Python 3.13 or newer. Install it with uv or pip:

uv tool install opencited
pip install opencited

Either gives the command opencited, with opencited mcp for the MCP server and opencited ask for questions. An MCP client can also start the server without an installation, with uvx opencited mcp, as below.

The MCP server

The MCP server also works on its own, for MCP clients that start a server over stdio or connect over Streamable HTTP. It offers three tools, search_tables, get_table_metadata and query_table, and every query result carries a provenance record.

The commands below start the server with uvx opencited mcp, which runs the package from PyPI.

Claude Code

claude mcp add --transport stdio opencited -- uvx opencited mcp

Over Streamable HTTP, start the server with uvx opencited mcp --http, which listens on 127.0.0.1 only, and add it with:

claude mcp add --transport http opencited http://127.0.0.1:8765/mcp

VS Code and other clients that read .mcp.json

Put this in .mcp.json at the root of a project. Claude Code reads the same file for servers that a project shares.

{
  "mcpServers": {
    "opencited": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opencited", "mcp"]
    }
  }
}

Options

opencited mcp --help lists the options. --http serves Streamable HTTP, on port 8765 unless --port sets another. SSB's metadata and data responses are cached in the user's cache directory until the next 08:15 Norwegian time; --cache-dir moves the cache and --no-cache turns it off. --snapshot-dir keeps a snapshot of each query result, which the server never changes once written; a result with a value wider than 38 digits gets none. From 05:00 to 08:15 Norwegian time, query_table returns an error instead of data, since SSB revises figures then.

Asking a question

opencited ask answers a question with a language model of your choice, through an endpoint that is compatible with the OpenAI chat completions API, such as a hosted provider or a local server. Three variables name the endpoint, the model and the variable that holds the API key:

export OPENCITED_MODEL_URL=https://api.example.org/v1
export OPENCITED_MODEL=model-name
export OPENCITED_MODEL_KEY_VARIABLE=EXAMPLE_API_KEY
opencited ask "Hvor mange bor i Norge?"

For example, in the published run of 2026-10-18, the question "By how many per cent did the consumer price index change from September 2025 to September 2026?" got this answer:

The consumer price index rose by 3.4 per cent from September 2025 to September 2026 [1].

The index stood at 100.6 in 2025M09 and 104.0 in 2026M09, in the series with 2025=100 [2]. The change is calculated from those two index values [1] [2].

Sources:
[1] Calculation from table 14710, https://www.ssb.no/en/statbank/table/14710, retrieved 2026-10-18 14:50 UTC. Steps: chg, sep25, sep26. The steps with their SQL are in --json.
[2] Statistics Norway (SSB), table 14710: Consumer price index (2025=100), by month. https://www.ssb.no/en/statbank/table/14710, retrieved 2026-10-18 14:50 UTC

The answer comes in the language of the question, or in the one --language no or --language en sets, with numbered sources. --json prints every record: the citations with their provenance records and the cells used, the calculations with their SQL, the gate report, the model and its settings, and the usage. The command exits with 0 for an answer, 3 for a refusal, 1 when the run fails and 2 when the configuration cannot be used.

Each question is limited to 12 model calls, 20 tool calls, 100,000 tokens and 300 seconds. The architecture page lists the variables that change these limits and set prices, a temperature, a seed and extra request fields, such as the one that turns off a model's thinking mode.

Sources

Source	Publisher	Status
StatBank	Statistics Norway (SSB)	First source, in progress (M1)
Other national statistics offices	Various	Candidate
International statistics	Eurostat, OECD and others	Candidate
Health guidance	Approved health authorities	Candidate, risk review first

Every source passes a review before it is added. See sources.

Documentation

• Architecture
• Roadmap
• Decision records
• Specifications
• Sources
• Development and releasing
• Contributing and security policy

Licence

The code is licensed under the Apache License 2.0. Evaluation datasets will be published under CC BY 4.0. Data from each source keeps its own licence.

Data from StatBank comes from Statistics Norway (SSB) and is licensed under CC BY 4.0, as SSB's API guide states.

OpenCited is an independent project. It is not affiliated with or endorsed by Statistics Norway or any other source it uses.

Author

Built and maintained by Daniel Norlan (LinkedIn).