MCP & AI Agents

Give your AI agents direct access to SwarmV's global edge memory. Integrate instantly using the Model Context Protocol (MCP) or native platform SDKs.

What are the Use Cases?

🧠 Long-Term Agent Memory

Agents can write facts, user preferences, and summaries to SwarmV. Because it's a vector database, they can semantically retrieve this memory later across completely different chat sessions.

🔄 Multi-Agent Handoffs

Agent A gathers research and writes the vector embeddings to SwarmV. Agent B wakes up in a different datacenter, searches the edge memory, and instantly continues the workflow.

Desktop Clients (Claude & Cursor)

You can plug SwarmV directly into your local IDE or Claude Desktop app to give the AI access to your edge context.

🔐 Each MCP server acts as one user

Don't put an API key in an MCP config. The server gets a short-lived user token from your backend instead, so the agent can only see and change what that user can, and nothing in a prompt can make it act as someone else. Tokens are refreshed automatically when they expire. See Authentication for the token endpoint.

claude_desktop_config.json (Node.js)

{
  "mcpServers": {
    "swarmv": {
      "command": "npx",
      "args": ["-y", "@swarmv/mcp-server"],
      "env": {
        "SWARMV_TOKEN_URL": "https://your-backend.example.com/swarmv-token",
        "SWARMV_TOKEN_URL_AUTH": "<the signed-in user's session credential>"
      }
    }
  }
}

claude_desktop_config.json (Python)

{
  "mcpServers": {
    "swarmv-py": {
      "command": "uv",
      "args": ["tool", "run", "swarmv-mcp"],
      "env": {
        "SWARMV_TOKEN_URL": "https://your-backend.example.com/swarmv-token",
        "SWARMV_TOKEN_URL_AUTH": "<the signed-in user's session credential>"
      }
    }
  }
}

Other ways to provide credentials

SWARMV_TOKEN_URL (recommended): your endpoint returning {"token": "…"}. SWARMV_TOKEN_URL_AUTH, if set, is sent as a Bearer credential.
SWARMV_USER_TOKEN: a fixed token for quick tests. It expires within an hour.
SWARMV_API_KEY + SWARMV_USER_ID: local development only. The server creates its own tokens for that one user, but keeps a backend key on the machine. Without SWARMV_USER_ID the server refuses to start.

The tools are read_from_memory (search, returning each hit's stored metadata) and write_to_memory, which needs a container_id the user can edit and keeps the note text in metadata.text. Vectors are padded or truncated to 768 dimensions (set SWARMV_DIM to change it).

Programmatic Agents

When building autonomous agents in code, you can easily wire SwarmV into any major AI framework.

1. OpenAI (Native Function Calling)

For raw OpenAI scripts, wrap the SwarmV SDK directly into your tool definitions.

Python

import openai
from swarmv import SwarmV

# Act as the end user: a user token from your backend (see Authentication),
# so searches only return what this user may see.
memory = SwarmV(token_provider=fetch_swarmv_token)

# Define the tool for OpenAI
tools = [{
    "type": "function",
    "function": {
        "name": "search_memory",
        "description": "Search the agent's global edge memory",
        "parameters": {
            "type": "object",
            "properties": {"query_vector": {"type": "array", "items": {"type": "number"}}}
        }
    }
}]

# When the model calls the tool:
def execute_tool(call):
    if call.function.name == "search_memory":
        args = json.loads(call.function.arguments)
        results = memory.search(query=args["query_vector"], top_k=5)
        return str(results)

2. Vercel AI SDK

Use SwarmV inside Next.js or Node using the Vercel AI SDK's tool() helper.

TypeScript

import { generateText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
import { SwarmV } from '@swarmv/sdk';

// Act as the end user, so searches only return what they may see.
const memory = new SwarmV({ getToken: () => fetchSwarmvToken(session) });

const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Check my memory to see what my favorite color is.',
  tools: {
    readMemory: tool({
      description: 'Read from the global edge vector memory',
      parameters: z.object({
        vector: z.array(z.number()).describe('The embedding vector of the query')
      }),
      execute: async ({ vector }) => {
        const results = await memory.search(vector, { topK: 5 });
        return results;
      },
    }),
  },
});

3. LangChain

LangChain provides first-class support for MCP Servers. You can dynamically load SwarmV's tools without writing any custom wrapper code!

Python

from langchain_mcp import MCPClient
from langchain_openai import ChatOpenAI
from langchain.agents import initialize_agent, AgentType

# 1. Connect to the SwarmV MCP Server
mcp = MCPClient(
    command="uv",
    args=["tool", "run", "swarmv-mcp"],
    env={"SWARMV_TOKEN_URL": "https://your-backend.example.com/swarmv-token"}
)

# 2. Extract tools dynamically (read_from_memory, write_to_memory)
swarmv_tools = mcp.get_tools()

# 3. Give them to your LangChain Agent!
llm = ChatOpenAI(model="gpt-4o")
agent = initialize_agent(
    tools=swarmv_tools, 
    llm=llm, 
    agent=AgentType.OPENAI_FUNCTIONS
)

agent.run("Save this thought to memory: I need to buy milk tomorrow.")

4. Google Gemini (Google AI SDK)

Gemini supports powerful native function calling. You can directly expose SwarmV to Gemini models to give them edge-memory capabilities.

Python

import google.generativeai as genai
from swarmv import SwarmV

memory = SwarmV(token_provider=fetch_swarmv_token)  # a token for the end user

def search_edge_memory(query_vector: list[float]) -> str:
    """Search the global edge vector memory for context."""
    results = memory.search(query=query_vector, top_k=5)
    return str(results)

model = genai.GenerativeModel(
    model_name='gemini-1.5-pro',
    tools=[search_edge_memory]
)

response = model.generate_content("Look up my user profile vector in edge memory.")
print(response.text)

5. Databricks (MosaicML / Model Serving)

When serving custom models or using Databricks Foundation Model APIs, use LangChain or the native Databricks SDK to route function calls to SwarmV.

Python

from mlflow.deployments import get_deploy_client
from swarmv import SwarmV

client = get_deploy_client("databricks")
memory = SwarmV(token_provider=fetch_swarmv_token)  # a token for the end user

response = client.predict(
    endpoint="databricks-meta-llama-3-70b-instruct",
    inputs={
        "messages": [
            {"role": "user", "content": "Retrieve my past preferences."}
        ],
        "tools": [{
            "type": "function",
            "function": {
                "name": "search_edge_memory",
                "description": "Fetch semantic context from SwarmV edge"
            }
        }]
    }
)