Metablox MCP Documentation

Overview

The Metablox MCP Server lets AI assistants — such as Claude, Cursor, Perplexity, and other MCP-compatible clients — interact with your Metablox account. Through it, an AI assistant can create and manage your memories, organize collections, upload photos, and more — all with your explicit permission.

Metablox provides two server modes to suit different integration needs:

Quick Start

Remote Server (Claude, Perplexity, etc.)

If your AI tool supports remote MCP connections, point it at the Metablox endpoint — no local setup needed.

1. Enable MCP in your Metablox account

   Go to Account Settings → MCP Access on metablox.co and flip the master toggle on. Choose which permissions to grant (e.g., read memories, create collections).

2. Authorize your AI app

   When your AI client connects, you'll be redirected to Metablox to approve the requested scopes. After approval, the app receives an OAuth 2.1 access token automatically.

3. Start using it

   Ask your AI assistant things like "Show me my recent memories" or "Create a new collection called Vacation 2025". The assistant will use the MCP tools on your behalf.

Local Server (Claude Desktop, Cursor)

1. Install dependencies

   pip install "mcp[cli]>=1.2.0" httpx python-dotenv

2. Configure environment

   Create a .env file in the project root (or set the variables directly):

   # .env
   METABLOX_API_BASE_URL=https://metablox.co/api/v1
   METABLOX_API_TOKEN=your_api_token_here

3. Add the server to your AI client

   In your client's MCP configuration file (e.g., claude_desktop_config.json):

   {
     "mcpServers": {
       "metablox": {
         "command": "python",
         "args": ["-m", "mcp_server"],
         "env": {
           "METABLOX_API_BASE_URL": "https://metablox.co/api/v1",
           "METABLOX_API_TOKEN": "your_api_token_here"
         }
       }
     }
   }

4. Verify the connection

   Open your AI client and ask it to call get_my_profile. If it returns your Metablox profile, you're all set.

Authentication

Remote Server — OAuth 2.1 with PKCE

The remote MCP server uses OAuth 2.1 with PKCE (Proof Key for Code Exchange) for secure authorization. This is the same flow used by modern mobile and single-page apps, and it means client secrets are never exposed.

Token Details

Access tokens expire after 30 days. Refresh tokens expire after 90 days. When you refresh a token, the old token is atomically deactivated and a new token pair is issued (token rotation). Both MCP <token> and Bearer <token> header formats are accepted.

Local Server — API Token

The local server authenticates using a static API token set via the METABLOX_API_TOKEN environment variable. Alternatively, you can call the login tool at runtime with your username and password to obtain a session token.

Token Info Endpoint

Validates a token and returns its scopes, client ID, and expiry. Useful for debugging authorization issues.

Scopes & Permissions

Access is controlled at three levels: OAuth scopes requested by the app, user-level permission toggles, and per-tool enable/disable switches. All three must allow an action for it to succeed.

Available Scopes

User Permission Controls

Every user has a master toggle and granular per-resource permissions on their MCP settings page. Even if an app requests memory:delete, the operation will fail unless the user has also enabled memory deletion in their settings.

Per-Tool Controls

Individual tools can be disabled by the user via the MCP settings page. For example, you might allow list_memories but disable delete_memory — giving you precise control over what any connected AI can do.

Management Endpoints

Remote Server

The remote MCP server is hosted at https://metablox.co/mcp/ and uses Streamable HTTP transport. AI platforms send MCP protocol messages over HTTPS, and the server translates them into authenticated Metablox API calls.

The remote server exposes the core memory and collection tools. For the full set of tools (including Blox info, leaderboards, and auctions), use the local server.

Local Server

The local server runs on your machine and communicates with your AI client over stdio. It provides the complete tool set — memories, collections, moments, marks (reactions), Blox info, leaderboards, and auctions.

Requirements

Python 3.12+ and the following packages:

mcp[cli]>=1.2.0
httpx>=0.27.0
python-dotenv>=1.0.0

Environment Variables

Running Standalone

# From the metablox-app root directory
python -m mcp_server

Tools Reference

Below is the complete set of tools available through the Metablox MCP server. Tools marked REMOTE are available on both the remote and local servers. All others are local-server only.

Rate Limits

The MCP API enforces rate limiting at three levels to ensure fair usage and platform stability:

Audit Log

Every MCP operation is recorded in an audit log. You can review exactly what any connected AI assistant has done on your behalf — which tools were called, what resources were accessed or modified, and when.

Each log entry includes the action performed, the resource type and ID, the application that made the request, your IP address, user agent, and a timestamp. Use this to monitor AI assistant activity and verify that connected apps are behaving as expected.

Troubleshooting

Common Issues

Getting Help

If you're still stuck, reach out to [email protected] or visit the Metablox Support Center. When reporting an issue, include your audit log entries and the error response from the MCP tool call.