MCP

NDI speaks Model Context Protocol, so an agent can call parse, extract, search, and the rest as tools. Hosted and local servers expose the same catalog. Prefer uvx ndi-mcp (or pip install ndi-mcp). The older ndi-sdk[mcp] extra still resolves to that package.

	Hosted (`https://ndi-api.nace.ai/v1/mcp`)	Local (`uvx ndi-mcp`)
Install	none	Python 3.11+, `uvx`
Auth	`X-API-Key` or `Authorization: Bearer` header	`ndi-mcp login`, or `$NDI_API_KEY`
Files on your machine	public URLs only	uploaded straight from disk
Best for	quick setup, shared and CI agents	coding agents working on local files

Hosted

Paste this into the agent’s MCP config. Mint the key on the API keys page; do not commit it.

{
  "mcpServers": {
    "ndi": {
      "type": "http",
      "url": "https://ndi-api.nace.ai/v1/mcp",
      "headers": { "X-API-Key": "ndi_sk_..." }
    }
  }
}

For another NDI deployment, use its API host: <NDI_BASE_URL>/v1/mcp, with no trailing slash. The server also accepts the key as Authorization: Bearer ndi_sk_.... The hosted server runs in our cloud, so it cannot see your filesystem. upload_document and upload_file refuse a local path there. Pass a public URL, or run the local server.

Local

uvx ndi-mcp login
claude mcp add ndi -- uvx ndi-mcp

ndi-mcp login opens the NDI console in your browser. Approve there; the CLI stores the minted key in ~/.ndi/config.toml. Pass --api-key (or set $NDI_API_KEY) to skip the browser. Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "ndi": {
      "command": "uvx",
      "args": ["ndi-mcp"]
    }
  }
}

opencode — add to opencode.json:

{
  "mcp": {
    "ndi": {
      "type": "local",
      "command": ["uvx", "ndi-mcp"]
    }
  }
}

$NDI_API_KEY is read first; otherwise the key saved by ndi-mcp login. Local files go through upload_document, then parse_document / extract_data with the returned upload_id.

Tools

Same catalog on hosted and local. Names map to the Python SDK:

MCP tool	SDK
`upload_document`	`client.documents.create_upload`
`parse_document`	`client.documents.parse`
`split_document`	`client.documents.split`
`classify_document`	`client.documents.classify`
`extract_data`	`client.documents.extract`
`ground_items`	`client.documents.ground`
`validate_extract_schema`	`client.documents.validate_extract_schema`
`evaluate_systemone`	`client.systemone.evaluate`
`get_job`	`client.jobs.get`
`wait_for_job`	`client.jobs.wait`
`list_jobs`	`client.jobs.list`
`cancel_job`	`client.jobs.cancel`
`create_workspace`	`client.workspaces.create`
`list_workspaces`	`client.workspaces.list`
`get_workspace`	`client.workspaces.get`
`set_global_context`	`client.workspaces.update(global_context=...)`
`workspace_stats`	`client.workspaces.stats`
`delete_workspace`	`client.workspaces.delete`
`upload_file`	`client.files.upload`
`upload_and_ingest_file`	`client.upload_and_ingest`
`list_files`	`client.files.list`
`ingest_workspace`	`client.ingestion.ingest`
`automatic_search`	`client.search.automatic`
`qa`	`client.search.qa`
`deep_search` (deprecated)	`client.search.deep`
`fact_search` (deprecated)	`client.search.fact`
`je_testing`	`client.search.je_testing`
`start_ledger_understanding`	`client.workspaces.start_ledger_understanding`
`get_ledger_understanding`	`client.workspaces.get_ledger_understanding`
`list_ledger_sources`	`client.workspaces.list_ledger_sources`
`select_ledger_sources`	`client.workspaces.select_ledger_sources`
`get_ledger_selection`	`client.workspaces.get_ledger_selection`
`qa_file`	`client.tools.qa_file`
`query_tables`	`client.tools.query_tables`
`get_documentation`	shipped topic files via `ndi_mcp.docs`

Ask get_documentation with a topic (parse, extract, auth, workspaces, …) before writing integration code. To decide between automatic_search, qa, je_testing, qa_file, and query_tables for a question, follow Choose the right tool. deep_search and fact_search are deprecated: use qa or automatic_search instead of deep_search, and automatic_search with mode="fact" instead of fact_search. Both keep working until they are retired. start_ledger_understanding measures the ingested journal package; get_ledger_understanding reads the latest report. list_ledger_sources, select_ledger_sources, and get_ledger_selection confirm a source selection; pass the returned selection_id to start and get. Without force, an unchanged package republishes the stored report. A run already in flight returns 409 ledger_understanding_in_progress. A failed tool call returns an error result (isError: true) whose text is <code>: <message>, such as unauthorized: …. A refused request (invalid_request) adds one - <field>: <message> line per refused field, up to five, without repeating the values you sent. Some arguments are checked before any call; for example, evaluate_systemone refuses an unknown question type with the validation library’s message. After automatic_search, qa, or je_testing succeeds, poll every grounding job id with wait_for_job. For automatic_search, those ids are on result.output when fact search answered (or a stored deep route), and an agent answer’s are on result.output.answer when present; for qa, on result.answer when present; for je_testing and the deprecated search tools, on result.grounding_job_ids. Do not call ground_items for those evidences.

Getting started

Guides

Agents

Concepts

Troubleshooting

Hosted

Local

Tools

Next steps

​Hosted

​Local

​Tools

​Next steps

Hosted

Local

Tools

Next steps