docs
Open dashboard

Custom AI agents

When Claude Desktop / Cursor isn't enough and you want your own agent — say, the Anthropic API directly from Python — you have two paths.

Option 1: Use our MCP server

The Anthropic SDK supports MCP natively. Run nevios_mcp as a subprocess and Anthropic handles the rest:

from anthropic import Anthropic

client = Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=4096,
    mcp_servers=[
        {
            "type": "stdio",
            "command": "uv",
            "args": [
                "--directory", "/path/to/apps/mcp",
                "run", "python", "-m", "nevios_mcp.server"
            ],
            "env": {
                "NEVIOS_API_KEY": "nev_pat_...",
                "NEVIOS_WORKSPACE_ID": "...",
            }
        }
    ],
    messages=[{"role": "user", "content": "Create a new note ..."}],
)

Option 2: Call REST directly

When you don't need a tool-use abstraction and want to hit the API yourself:

import os
import uuid
import httpx

NEVIOS_KEY = os.environ["NEVIOS_API_KEY"]
WORKSPACE = os.environ["NEVIOS_WORKSPACE_ID"]

async with httpx.AsyncClient() as client:
    res = await client.post(
        "https://api.nevios.io/api/v1/notes",
        headers={
            "Authorization": f"Bearer {NEVIOS_KEY}",
            "X-Workspace-Id": WORKSPACE,
            "Idempotency-Key": str(uuid.uuid4()),
        },
        json={
            "title": "AI-generated note",
            "content_text": "...",
            "kind": "page",
        },
    )
    res.raise_for_status()

OpenAI / GPT

The OpenAI tools API doesn't yet support MCP natively (at the time of writing). Either:

  1. Use OpenAI tool-calling and define functions yourself (one-to-one mapping to REST endpoints).
  2. Use OpenAI's agents SDK when its MCP support lands.
  3. Switch to the Anthropic API — first-class MCP support today.

Architecture tips

  • Idempotency. Always send Idempotency-Key on mutations. When an AI retries, it gets the same response and doesn't duplicate.
  • Limit scopes. Mint a key with only what the agent needs. The audit log in the dashboard (coming soon) will show what each agent actually did.
  • Stability. Don't memorise UUIDs across conversations. Look them up each time via search_notes / list_workbooks — they're stable, but a user might delete or rename something between turns.