Onto MCP Server

FastMCP server for Onto platform access via a configured Onto API key.

Runtime Contract

Required environment variables:

• all transports: ONTO_API_BASE
• stdio only: ONTO_API_KEY

Optional environment variables:

• MCP_TRANSPORT values: stdio, http
• PORT
• SESSION_STATE_API_BASE
• SESSION_STATE_API_KEY

The server no longer supports login/password, OAuth code exchange, or manual user token flows.

Public HTTP /mcp accepts either X-API-Key or the retained X-Onto-Api-Key. Header names are ASCII case-insensitive, but values are compared as untrimmed bytes. One occurrence is accepted. One occurrence of each name is accepted only when the non-empty values are byte-identical. Empty or SP/HTAB-only values, repeated fields, values containing a comma, conflicting dual headers, and an API key combined with any Bearer Authorization occurrence are rejected before MCP dispatch with a generic response. Bearer-only authorization has no API-key semantics; OAuth remains a separate contract.

An accepted HTTP credential is projected to Core as exactly one X-API-Key. HTTP never falls back to server-side ONTO_API_KEY, and neither X-Onto-Api-Key nor Authorization is projected as Core API-key authentication. Stdio continues to require ONTO_API_KEY and projects it as one X-API-Key. Header-name configuration does not alter this contract. Credential values must not appear in responses, errors, logs, traces, or metrics. This authentication bridge does not change MCP tool names, schemas, protocol metadata, or result envelopes.

SESSION_STATE_API_KEY remains optional unless you use the session-state helper tools.

Tools

• how_to_use_onto_mcp(question="", safety_mode="read_only")
• list_available_realms()
• list_realm_agents(realm_id)
• get_realm_agent(realm_id, slug)
• preflight_realm_agent_governance_proposal(realm_id, proposal_artifact_id)
• admit_realm_agent(realm_id, candidate)
• about_onto(focus="")
• search_templates(name_part, realm_id=None, include_children=False, include_parents=False)
• search_relation_templates(realm_id, relation_type_name="", meta_ids=None)
• search_entities_by_relations(realm_id, searched_meta_ids, predicates=None, include_descendants=True, first=0, offset=100, sort=None)
• search_agent_memory(realm_id, target_kind, target_id, memory_kind="", status="", reality="", author_id="", source_ref="", branch_id="", query="", first=0, offset=100)
• get_agent_memory_record(realm_id, record_id)
• create_memory_artifact_draft(realm_id, artifact_path, artifact_kind, write_mode, body, summary, source_ref, source_context=None, review_destination=None, agent_principal="", targets=None)
• get_memory_artifact(realm_id, artifact_id)
• get_memory_artifact_by_path(realm_id, artifact_path)
• get_own_memory_artifact_draft_by_path(realm_id, artifact_path, agent_principal)