How the Vilix AI MCP works

Vilix AI is a memory layer that any MCP-capable AI tool can read from and write to. This page explains how that connection actually works, first in plain English for anyone using Vilix AI, then in more detail for developers building their own MCP client.

Part 1, The overview

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI tools like ChatGPT, Claude, Cursor, and Codex talk to outside services through a single uniform interface. Instead of every AI app inventing its own plugin system, MCP gives them all a common language for connecting to memory, files, calendars, databases, and other services.

Vilix AI exposes a memory layer through MCP. When your AI tool is connected to Vilix AI, it can pull context from your past conversations before it answers you, and save the new exchange after.

What Vilix AI exposes

The core conversation loop uses two tools:

• get_context, your AI calls this before it replies. It passes the user’s latest message. Vilix AI runs retrieval and returns recent messages, related memories, related past conversations, and any active instructions you’ve set.
• save_turn, your AI calls this after it generates the final reply, before sending it to you. It passes the user message, the assistant message, and a source label (which tool the exchange happened in). Optionally, it reuses the chat_id from an earlier save so the conversation stays grouped.

Vilix AI also exposes search, recent messages, projects and tasks, personal rules, reusable skills and agent inbox tools. Use MCP tools/list to discover the current inventory and input schemas. The two tools above are the starting point for conversation memory.

The flow

user message
  → get_context(user_prompt)
    → recent_messages, user_memories, related_conversations, instruction
  → AI generates reply (using that context)
  → save_turn(user_message, assistant_message, source, chat_id?)
  → reply is sent to the user

How you connect

Connect each client separately to the same Vilix AI account. For clients that support browser authorization, use OAuth:

1. Open your AI tool’s MCP / integrations settings.
2. Paste the Vilix AI MCP URL.
3. Approve the OAuth sign-in prompt in your browser.

Then enable the memory tools and add the auto-memory instructions from Get started. Headless agents can instead use a Vilix AI API key as a Bearer header. Follow the guide for your exact client, device and account; one approval does not configure other tools.

The URL

Use this Streamable HTTP endpoint in each supported client. OAuth clients can discover authorization from it; API-key clients also need the Bearer header.

https://api.vilix.ai/mcp

Per-tool screenshots and walk-throughs for Claude, ChatGPT, Cursor, and Codex live on the Get started page.

Part 2, For developers

If you’re building or configuring an MCP client and you want to integrate with Vilix AI directly, this section has the protocol-level details.

Transport

Vilix AI speaks MCP over Streamable HTTP, configured for stateless JSON responses. Each request is an independent POST and JSON exchange; the service does not require a long-lived event stream.

Base host: https://api.vilix.ai.

stdio transport is not supported, Vilix AI is a hosted service, so a remote HTTP transport is the only mode.

Protocol

Standard JSON-RPC 2.0 as defined by the Model Context Protocol specification. There is no custom envelope and no proprietary extension fields. If your MCP client speaks the spec, it speaks to Vilix AI.

Authentication

Vilix AI supports OAuth 2.0 and personal API keys. Authenticated MCP requests carry a Bearer token:

Authorization: Bearer <access_token>

You get that access token by walking through the OAuth sign-in flow. If your MCP client supports OAuth (ChatGPT, Claude.ai, Cursor, Codex all do), discovery is automatic, you just point the client at the MCP URL and it handles authorization, token exchange, and refresh on its own.

A few things worth knowing:

• Headless agents can use an API key. Open Agents → Create API key in Vilix AI. Copy the key when it is shown, then configure Authorization: Bearer YOUR_VILIX_API_KEY. This path works on MCP and uses the same account ownership and plan limits as OAuth. Keep the key private; revoke it in the dashboard when no longer needed.
• Refresh is handled by the client. OAuth access tokens are short-lived. MCP clients exchange the refresh token automatically when the access token expires, you don’t have to do anything.
• Expired tokens return 401. For OAuth, reconnect or refresh the session. For an API key, check whether it was revoked or expired and replace it in the client configuration.

Tool reference

get_context

Call this before generating a reply. Vilix AI runs retrieval and returns the context your AI should use to ground the answer.

Input:

Output: A text content block describing recent messages, user memories, related past conversations, and any active instruction memories. The shape is intentionally simple, your AI consumes it as context, the same way it consumes a system prompt.

save_turn

Call this after you’ve generated the final assistant reply, before sending it to the user. Persists the exchange and triggers Vilix AI’s memory extraction in the background.

Input:

Output: An acknowledgement that includes the chat_id for the conversation. Pass that chat_id back on subsequent save_turn calls in the same chat.

Example request and response

A typical get_context call over JSON-RPC:

Request

POST /mcp HTTP/1.1
Host: api.vilix.ai
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_context",
    "arguments": {
      "user_prompt": "Continue helping me with my launch plan."
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ recent_messages: [...], user_memories: [...], related_conversations: [...], instruction: \"...\" }"
      }
    ]
  }
}

The example shows a text content block. Current tools can also return structured content and advertised output schemas; use the actual tools/list schema when building a client.

Health check

GET https://api.vilix.ai/mcp/health

Returns 200 OK when the service is up. No Authorization header required. Use it for uptime monitoring or as a connection smoke test.

Errors

After the Pro trial, accounts move to Free if they do not upgrade. Existing history, semantic search and keyword search remain accessible. Reading and recalling memory is uncapped on every plan; daily allowances apply to new writes, and burst protection can briefly pace rapid reads.

Best practices

• Call order matters. get_context before you compose the reply; save_turn after the reply is finalized but before you send it to the user. Returning a reply without saving it leaves your memory thin.
• Reuse chat_id. Within a single conversation, capture the chat_id from the first save_turn and pass it back on every later save_turn in that chat. This keeps turns grouped for retrieval.
• Set source honestly. It’s the label Vilix AI uses to mark where a memory came from, useful when retrieval surfaces past context and the model needs to know whether something happened in ChatGPT, Claude, Cursor, etc.
• Don’t paraphrase the user message into get_context. Pass user_prompt verbatim. Vilix AI’s retrieval is tuned for the raw input.
• Use a system-prompt to enforce the pattern. The recommended prompt that wires get_context / save_turn into a model’s reply cycle is on the Get started page.

Part 3, Where to go next

• Get started, per-tool setup steps for Claude, ChatGPT, Cursor, and Codex, plus the system prompt that enforces the call order.
• Using the Vilix AI dashboard, a walkthrough of app.vilix.ai: search, export, deletion, plan and billing.
• Security, data handling, isolation, export, and deletion.

Need help?

Email support@vilix.ai for setup help, connection issues with ChatGPT / Claude / Cursor / Codex, billing, or account questions.

For vulnerability reports or security concerns, write to security@vilix.ai.