Build on the Ontology

MCP-native. Neo4j-backed. Workspace-scoped. Query your business ontology and code graph over MCP, REST, or the typed SDK — richer context, cheaper models, built-in evals.

Get started free Read the docs

Skip the Context Layer

Every Oxagen workspace is a typed knowledge graph your agent can query instantly — entities, relationships, and schema you control. Stop building context plumbing. Start building features.

Zero Cold Starts

Oxagen ingests from your sources into a workspace-scoped Neo4j graph. Your agent inherits real structure from day one — no waiting for a user to teach it what matters.

Cross-System Reasoning

Email, calendar, files, CRM, custom sources — all typed into the same ontology. Build features that reason across systems without writing the data layer yourself.

Overview

Everything you need to integrate with Oxagen.

Build plugins and tools on top of Oxagen's workspace knowledge graph — typed, queryable, and always current. The developer surface is open-by-design: MCP-native, OpenAPI- complete, and portable across agent stacks. Ship agents with deep, deterministic context on day one.

Base URL

All API endpoints are served under a single base URL. Append the path for each resource.

https://api.oxagen.ai/v1

Response Format

Every response is JSON. Successful responses return the resource directly. Errors return {"detail": "..."}.

{"status": "ok", "version": "0.2.1"}

Streaming

The agent chat endpoint supports Server-Sent Events (SSE) for real-time streaming of AI responses, tool calls, and results.

POST /v1/agent/chat/stream

Rate Limits

Authenticated requests are limited to 60 req/min per user. Public (unauthenticated) endpoints are limited to 10 req/min per IP.

X-RateLimit-Remaining: 58

Authentication

Authenticate with JWT tokens passed as Bearer tokens.

Oxagen uses Custom JWT (RS256) for authentication. Every authenticated request must include a valid JWT in theAuthorizationheader. The backend validates the token and resolves the user and tenant automatically.

bash

# Obtain a session token, then:
curl -X GET "https://api.oxagen.ai/v1/users/me" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json"

python

import httpx

TOKEN = "eyJhbGci..."  # JWT access token

resp = httpx.get(
    "https://api.oxagen.ai/v1/users/me",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(resp.json())

typescript

const resp = await fetch("https://api.oxagen.ai/v1/users/me", {
  headers: { Authorization: "Bearer " + token },
});
const user = await resp.json();

API Reference

Auto-generated from the live OpenAPI specification.

Loading API specification…

The Ontology

A typed, workspace-scoped knowledge graph of nodes and edges — the shared memory every agent in the workspace queries.

The ontology is the core data model. Every connected source (email, calendar, finance, docs, your own webhooks) feeds typed nodes and edges into a workspace- scoped Neo4j graph. Agents traverse that graph over MCP or REST to answer cross-source questions without duct-taping vectors, Postgres, and prompt scaffolding.

Node and edge types are free-form strings — the system accepts any type you define. The table below lists common types used by the AI classifier, but workspace-specific types (e.g. job_post, experiment, invoice) are discovered and created automatically as data flows in.

Common Node Types

Types are free-form strings. These are the most common types used by the AI classifier — you can create nodes with any type.

Type	Description
person	A person — contact, colleague, customer, teammate
business	A business, company, or organization
document	A document, file, spec, or note
message	An email, chat, or notification
meeting	A calendar meeting or scheduled event
task	A task, issue, or ticket
project	A project, sprint, or initiative
transaction	A financial transaction
account	A financial account, cost center, or budget
location	A physical place or venue
event	A general event

Common Relationship Types

Relationship types are free-form strings. These are the most common types. You can create relationships with any type.

Type	Description
belongs_to	Entity belongs to another (e.g. transaction → trip)
attended_by	Event attended by a person
paid_by	Transaction paid by a person or account
works_at	Person works at a business or organization
member_of	Person is a member of a group or organization
organized_by	Event or meeting organized by a person or business
scheduled_for	Entity scheduled for a specific date or event
occurred_during	Happened during a time period or trip
related_to	General association between entities
linked_to	Explicit link between entities
part_of	Entity is part of a larger entity
generated_by	Created by a workflow or agent

Building on the Graph

Use the REST API or MCP tools to create nodes, define edges, and query the graph. Here's an example that creates a project node and links a transaction to it:

python

import httpx

BASE = "https://api.oxagen.ai/v1"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

# 1. Create a project node
project = httpx.post(f"{BASE}/mcp", headers=HEADERS, json={
    "jsonrpc": "2.0", "id": 1,
    "method": "tools/call",
    "params": {
        "name": "create_node",
        "arguments": {
            "type": "project",
            "name": "Q2 Platform Launch",
            "description": "Workspace rollout, April 2026",
            "properties": {"quarter": "2026Q2", "owner": "eng"}
        }
    }
}).json()

project_id = project["result"]["content"][0]["text"]  # JSON with node id

# 2. Link an existing transaction to the project
httpx.post(f"{BASE}/mcp", headers=HEADERS, json={
    "jsonrpc": "2.0", "id": 2,
    "method": "tools/call",
    "params": {
        "name": "create_edge",
        "arguments": {
            "source_node_id": "<transaction-uuid>",
            "target_node_id": "<project-uuid>",
            "type": "belongs_to"
        }
    }
})

MCP Server

Beta

Connect AI tools directly to the ontology via the Model Context Protocol.

Oxagen exposes a Model Context Protocol (MCP) server that lets AI clients — Claude Desktop, custom agents, or any MCP-compatible tool — interact with the ontology directly. The server uses JSON-RPC 2.0 over HTTP. The MCP server is currently in beta and under active development.

MCP enables AI to search your knowledge graph, create entities, build relationships, and list connected data sources — all through a standardized protocol that works with any MCP client.

Connect with Claude Desktop

Add this to your claude_desktop_config.json:

json

{
  "mcpServers": {
    "oxagen": {
      "url": "https://api.oxagen.ai/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Available Tools

list_nodes

List or search nodes by type, name, or keyword

get_node

Get a single node by ID

list_edges

List edges for a node (inbound and outbound)

create_node

Create a new node with a free-form type

create_edge

Create an edge between two nodes

list_types

List types currently in use in your workspace ontology

list_connections

List connected data sources (Gmail, Calendar, Plaid, etc.)

list_artifacts

List generated artifacts (reports, dashboards, summaries)

Example: List Nodes

bash

curl -X POST "https://api.oxagen.ai/v1/mcp" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_nodes",
      "arguments": {
        "query": "q2 launch expenses",
        "type": "transaction",
        "limit": 10
      }
    }
  }'

Protocol Reference

Method	Description
initialize	Handshake — returns server info and capabilities
tools/list	List all available ontology tools with input schemas
tools/call	Execute a tool with the given arguments

The Ontology Is Built. Now Build What's Next.

Workspaces ship with typed entities, edges, and connected data sources. Your plugin turns that ontology into action — domain agents, automations, analytics, and MCP tools.

Get started free Read the docs