@infona-ai/mcp

MCP (Model Context Protocol) server for Infona. Gives AI agents tools to query, search, ingest, export, enrich, and manage your context graphs (knowledge graphs) in natural language.

Install / run

Package: @infona-ai/mcp. Primary binary: infona-mcp. Compatibility alias: onta-mcp (same entrypoint). There is no bare mcp bin.

No install needed — use npx:

npx -y -p @infona-ai/mcp infona-mcp

Or install globally:

npm install -g @infona-ai/mcp
infona-mcp

Claude Desktop / Cursor / Claude Code

Local OSS (no API key):

{
  "mcpServers": {
    "infona": {
      "command": "npx",
      "args": ["-y", "-p", "@infona-ai/mcp", "infona-mcp"],
      "env": {
        "INFONA_API_URL": "http://localhost:8000",
        "INFONA_TENANT": "default"
      }
    }
  }
}

Hosted Infona also needs INFONA_API_KEY and your workspace id in INFONA_TENANT.

Tools exposed

The server registers 37 tools, plus 1 more (list_local_files) when you opt in by configuring INFONA_LOCAL_FILES_DIR (see Environment):

• agent — the single conversational front door to the Ask-AI agent. Send a natural-language message; the agent classifies intent and either answers a question, asks a clarifying question, or proposes a multi-step plan (enrich attributes, clean/normalize values, merge duplicates, inspect/extend the ontology). A plan is not executed until you confirm it by calling agent again with the returned plan_id as confirm_plan_id. Planning is free; any paid step a plan contains (e.g. web enrichment) is authorized server-side at execute time, so confirming honors your tenant's entitlements.
• list_knowledge_graphs — list available KGs and their descriptions.
• ask — ask a natural-language question against a context graph; returns the answer (and an explanation when available).
• search — semantic + keyword (hybrid) search over free-text attributes of entities: find which entities mention/discuss a topic, with a matching snippet as the citation. Reads the derived index (not live triples). When the embedding service is unavailable or the semantic index is off, the tool still answers keyword-only and says so (reduced recall); use grep for an index-free literal scan of one graph. Use ask for aggregate or structured questions.
• grep — literal substring search across every literal value in one context graph, by scanning its triples directly (no index). The exact-string debugging counterpart to search: it finds values search cannot see because they were never indexed. Plain substring matching, not regex; unranked, and can be slow on a large graph, so it is bounded to one KG and rate-limited.
• view_ontology — show the ontology (types, attributes, relationships, and type descriptions) across your context graphs, plus the canonical skills prompt-block for those types. Tenant-wide and declaration-only; for one graph's actual data coverage use inspect_graph_schema.
• inspect_graph_schema: inspect ONE context graph's schema with population data, i.e. per type, which attributes and relationships actually carry data there and on what share of its entities. Declared-but-empty types and attributes are listed and marked EMPTY, so a missing slot is never confused with a non-existent one. Use it before asking for specific attributes so you never guess between similar names.
• create_knowledge_graph — create a new, empty KG (optionally with a description).
• delete_knowledge_graph — delete a KG and all of its data (irreversible).
• ingest_csv — ingest a CSV file by absolute path into a named KG; the schema is inferred automatically. Set join_on to merge each row onto the existing entity that carries the same key value instead of minting duplicates.
• ingest_text — ingest free-form text (or JSON) into a named KG without writing a file first. Posts through the same canonical POST /graphs/{tenant}/ingest route as the CLI's infona ingest --text (LLM entity extraction → ontology resolve → insert). Use for notes, meeting summaries, or any unstructured knowledge; use ingest_csv for tabular files on disk.
• ingest_dlt — extract a 3rd-party REST or SQL source via dlt and ingest the rows into a named KG. Posts the frozen {source, map, kg} body through the same SDK method (ingestDlt) the CLI and Explorer use. The Infona backend needs the optional extra (pip install infona-client[dlt]); if it is missing the tool returns that install hint. Auth is BYOK (env:VAR).
• export_kg — export a context graph's instance data as JSON (default) or CSV. Same canonical GET /graphs/{tenant}/kgs/{kg}/export route as the CLI's infona export (Client.exportKg). Optional type and limit filters; large dumps are truncated in the tool response with a note (use filters or the CLI for a full file).
• er_rebuild — second-pass entity resolution: collapse intra-batch duplicate fragments in an already-ingested KG. Same Client.erRebuild path as the CLI's infona er rebuild (POST …/explore/kgs/{kg}/er-rebuild, 300s timeout). Synchronous; use after messy ingest when duplicates remain.
• evolve_ontology — resolve a fuzzy natural-language ontology-evolution ask (no exact names needed); auto-applies high-confidence changes and returns a summary plus any proposals to confirm.
• apply_ontology_change — confirm and commit a single proposal returned by evolve_ontology.
• apply_ontology_changes — confirm and commit several proposals from evolve_ontology in one call (one round-trip instead of N; idempotent, per-proposal outcomes).
• schedule — set up a recurring standing alert / scheduled refresh (or list existing ones): watch values on a cadence and deliver a change payload to a webhook only when they change.
• list_jobs — list background jobs (enrichment, dedupe, reconciliation, web-discovery) for the tenant; use it to check on async work the agent tool kicked off.
• get_job — full record + live progress of a single background job by id (returns instantly with current status).
• wait_for_job — block server-side until a background job settles (or a bounded timeout), then return its status + progress — so one call covers a whole wait window instead of polling get_job in a loop.
• list_local_files: opt-in, off by default. List the .csv / .json / .jsonl files in a directory you have explicitly granted, so the agent can pass a real absolute path to ingest_csv instead of guessing one. Only registered when INFONA_LOCAL_FILES_DIR resolves to an existing directory; otherwise it does not appear at all.
• list_records — one page of entity instances of a type (columns + rows). Same Client.exploreRecords path as the Explorer data table.
• get_entity — one entity's properties and incident relationships (Client.getEntity).
• type_summary — per-type inventory with the coverage (and samples, if any) the API already returns (Client.exploreSummary). Does not invent values.
• list_tenants — workspaces this API key can access. The MCP process tenant is INFONA_TENANT (there is no mid-session switch).
• create_tenant — create a workspace (writes the caller's tenant list). Does not change INFONA_TENANT for this process.
• recompute_stats — schedule a type-stats recompute for a graph (writes the stats graph, not instance data).
• list_skills / get_skill / validate_skill / put_skill / delete_skill — type-attached markdown skills. put_skill and delete_skill write the ontology overlay.
• skills_prompt_block — the exact skill text an agent is handed (GET …/skills/prompt-block). Not re-rendered locally. view_ontology includes this block so inspect sees tenant skills.
• list_functions / register_function / invoke_function / delete_function — type-attached HTTPS/Lambda endpoints. Register, invoke, and delete write the registry / graph.

Enrichment and cleaning/normalization are reached through the agent tool — it plans them and, on confirm, runs them as background jobs, so any paid step stays authorized server-side at execute time. Duplicate-fragment collapse after ingest is the er_rebuild tool (same path as infona er rebuild). Use list_jobs / get_job / wait_for_job to watch agent jobs finish.

Environment

Local OSS — same JSON as the root README (no INFONA_API_KEY):

{
  "mcpServers": {
    "infona": {
      "command": "npx",
      "args": ["-y", "-p", "@infona-ai/mcp", "infona-mcp"],
      "env": {
        "INFONA_API_URL": "http://localhost:8000",
        "INFONA_TENANT": "default"
      }
    }
  }
}

• INFONA_API_KEY — required for hosted (https://api.infona.ai). Optional for localhost / 127.0.0.1 (open-access OSS).
• INFONA_API_URL — default https://api.infona.ai. Local OSS: http://localhost:8000.
• INFONA_TENANT — default demo-tenant on hosted, default on localhost.
• INFONA_LOCAL_FILES_DIR: optional, unset by default. An absolute path to one directory (or several, joined by your platform's path separator, max 4) that the agent may LIST. Setting it registers the list_local_files tool; leaving it unset means that tool does not exist.

Env vars are INFONA_* only — there is no ONTA_* (or other legacy-prefix) fallback in this package.

INFONA_LOCAL_FILES_DIR and what it grants

This MCP server runs as a local process with your own filesystem permissions, and anything it returns is sent to a remote model. So local file listing is off until you name a directory, and it is scoped to exactly that directory:

"env": {
  "INFONA_API_URL": "http://localhost:8000",
  "INFONA_LOCAL_FILES_DIR": "/Users/you/infona-data"
}

What you are granting, precisely:

• The agent can see filenames, sizes and modification times of .csv, .json and .jsonl files inside that directory, up to 3 levels deep.
• No file contents are ever read by this tool. Contents leave your machine only when you ingest a specific file.
• Nothing outside the directory is visible: directory symlinks are not followed, every returned file must resolve back inside the root, and .. is rejected. The filesystem root (/) is refused as a value.
• Dotfiles, dot-directories and node_modules are skipped.
• One exception to the containment rule: a hardlink placed inside the directory that points at a file outside it is listed (name, size and modification time, never content). A hardlink cannot be distinguished from an ordinary file, and creating one already requires write access to the directory.

Point it at a directory that holds the data you intend to ingest, not at your home directory or /. Filenames inside the granted directory are themselves visible to the model, so avoid granting a directory whose filenames are sensitive.

License

Apache-2.0. See LICENSE.