Skip to main content

​
Overview

While our SDKs are the recommended way to integrate Jean Memory for most applications, we also provide a powerful, low-level API endpoint for advanced use cases. The Model Context Protocol (MCP) API is designed for developers who need direct control over the context engineering process or are building autonomous agents that can leverage Jean Memory’s tool-calling capabilities. This is the same endpoint that our enterprise partners, like Claude, use to integrate Jean Memory as a tool for their models.
When to use the MCP API:
  • You are building an autonomous AI agent.
  • You need to integrate Jean Memory as a callable tool for an existing LLM.
  • You require streaming responses using Server-Sent Events (SSE).
  • You need more control than the SDKs provide.

​
Endpoint URL

The primary endpoint for all MCP interactions is a single HTTP POST request: 
https://jean-memory-api-virginia.onrender.com/mcp/v2/{client_name}/{user_id}
  • client_name: A unique identifier for your application (e.g., my-agent, claude).
  • user_id: The unique identifier for the end-user.

​
Authentication

The MCP API uses the same secure authentication as our SDKs. All requests must include a valid JWT in the Authorization header. 
Authorization: Bearer <your_pkce_jwt>
For SDK Users: Our SDKs handle the PKCE flow and JWT tokens automatically—you don’t need to manage this manually. For Custom Clients: If you are building a custom client, you will need to implement a standard PKCE authentication flow to acquire a user-specific JWT token.

​
Request Body

The request body is a JSON object that specifies the tool you want to call and its parameters. 
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "tool_name": "jean_memory",
    "tool_params": {
      "user_message": "What have I been working on recently?",
      "is_new_conversation": false,
      "depth": 2
    }
  },
  "id": "1"
}

​
Key Parameters:

  • method: Should always be tools/call.
  • tool_name: The name of the tool you want to execute. Use jean_memory for all interactions.
  • tool_params: An object containing the parameters for the specified tool.

​
The jean_memory Tool

This is the primary tool for all MCP interactions. It provides intelligent context engineering with configurable depth levels. Tool Parameters:
  • user_message (string, required): The user’s complete message or query.
  • is_new_conversation (boolean, required): Set to true only for the very first message in a new conversation.
  • depth (integer, optional, default: 2): The desired context depth level.
    • 0: No context retrieval. Use for generic knowledge questions that don’t require personal context.
    • 1: Fast search for quick personal facts or simple lookups (sub-second response time).
    • 2: Balanced synthesis for conversational responses using AI-powered memory synthesis (3-5 seconds).
    • 3: Comprehensive analysis with deep document search and extensive memory correlation (20-30 seconds).

​
Server-Sent Events (SSE) for Streaming

For clients that support streaming (like many conversational AI applications), the MCP API can stream responses using SSE. This allows you to receive the response as it’s generated, improving the user experience. To enable streaming, include the Accept: text/event-stream header in your request. Example JavaScript Client: 
const clientName = 'your_client_name';
const userId = 'user_123';
const token = 'your_pkce_jwt'; // Acquired via your auth flow

const eventSource = new EventSource(
  `https://jean-memory-api-virginia.onrender.com/mcp/v2/${clientName}/${userId}`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      'Accept': 'text/event-stream',
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method: 'tools/call',
      params: {
        tool_name: 'jean_memory',
        tool_params: {
          user_message: "What are my current project goals?",
          is_new_conversation: false,
          depth: 2
        },
      },
      id: "1",
    }),
  }
);

eventSource.onmessage = (event) => {
  // Each chunk of the response will arrive here
  console.log('Received chunk:', event.data);
};

eventSource.onerror = (error) => {
  console.error('SSE Error:', error);
  eventSource.close();
};
Heartbeats: The API will send colon-prefixed comments (:heartbeat) periodically to keep the connection alive, especially through proxies like Cloudflare. Your client should be prepared to ignore these messages.

​
Example Response (Non-Streaming)

A standard, non-streaming POST request will receive a JSON response like this: 
{
    "jsonrpc": "2.0",
    "result": {
        "content": [
            {
                "type": "text",
                "text": "Based on your recent memories, you've been heavily focused on developing 'Jean Memory', an AI memory layer. This includes work on SDKs, comprehensive testing, and preparing for a YC application. You're also exploring machine learning applications in your data analysis work."
            }
        ],
        "tool_name": "jean_memory"
    },
    "id": "1"
}
⌘I