Remote MCP (Cloud) — Pensyve Docs

Connect any MCP-compatible client to Pensyve Cloud. No binary to install, no local storage to manage — just your API key.

The remote MCP server uses Streamable HTTP transport. Authentication works via API keys (psy_ prefix) or OAuth 2.1 (PKCE). Keys support three scopes: full, read-only, and write-only. See the Authentication guide for details on scopes, rotation, and security.

Prerequisites

Sign up for a Pensyve Cloud account
Create an API key at Settings → API Keys
Set the key in your environment:

export PENSYVE_API_KEY="psy_your_key"

Add to your shell profile (~/.bashrc, ~/.zshrc) to persist across sessions.

Connect Your Client

Pensyve Cloud uses standard Authorization: Bearer authentication over HTTP transport. Every client config below follows the same pattern: your API key goes in the headers block as a Bearer token, not in an env block.

Use headers with Authorization: Bearer, not env. The env block sets environment variables for a spawned server process — but remote MCP is HTTP, not a local process. The headers approach sends your key directly on every request, which is the correct pattern for HTTP-transport MCP.

Claude Code

Install the plugin (includes MCP config automatically):

claude plugins add pensyve

Or connect directly via MCP:

claude mcp add --transport http pensyve https://mcp.pensyve.com/mcp \
  --header "Authorization: Bearer $PENSYVE_API_KEY"

Claude Desktop

Add to your config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "pensyve": {
      "type": "http",
      "url": "https://mcp.pensyve.com/mcp",
      "headers": {
        "Authorization": "Bearer ${PENSYVE_API_KEY}"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "pensyve": {
      "type": "http",
      "url": "https://mcp.pensyve.com/mcp",
      "headers": {
        "Authorization": "Bearer ${PENSYVE_API_KEY}"
      }
    }
  }
}

VS Code (Copilot Chat)

Add to .vscode/mcp.json:

{
  "servers": {
    "pensyve": {
      "type": "http",
      "url": "https://mcp.pensyve.com/mcp",
      "headers": {
        "Authorization": "Bearer ${PENSYVE_API_KEY}"
      }
    }
  }
}

Cline

Add to your Cline MCP config:

{
  "mcpServers": {
    "pensyve": {
      "type": "http",
      "url": "https://mcp.pensyve.com/mcp",
      "headers": {
        "Authorization": "Bearer ${PENSYVE_API_KEY}"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "pensyve": {
      "serverUrl": "https://mcp.pensyve.com/mcp",
      "headers": {
        "Authorization": "Bearer ${PENSYVE_API_KEY}"
      }
    }
  }
}

Continue

Add to ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "pensyve",
        "transport": {
          "type": "streamable-http",
          "url": "https://mcp.pensyve.com/mcp",
          "headers": {
            "Authorization": "Bearer ${PENSYVE_API_KEY}"
          }
        }
      }
    ]
  }
}

Available Tools

The remote MCP server exposes 8 tools:

Tool	Metered	Description
`pensyve_recall`	Yes	Semantic + BM25 memory search
`pensyve_remember`	Yes	Store a fact as semantic memory
`pensyve_episode_start`	Yes	Begin an interaction episode
`pensyve_episode_end`	Yes	Close an episode
`pensyve_forget`	Yes	Delete an entity's memories
`pensyve_inspect`	Yes	List memories for an entity
`pensyve_status`	Free	Namespace info, memory counts, health
`pensyve_account`	Free	Plan, usage, and quota

Every metered tool call counts as one operation against your plan's usage pool. See Pricing for details.

For full tool parameter reference, see MCP Tools.

Verify Connection

Once connected, ask your agent to check the connection:

"What's my Pensyve status?"

The agent will call pensyve_status and return your namespace, memory counts, and health status.

Remote vs Local

	Remote (Cloud)	Local
Setup	API key only	Install binary + ONNX models
Storage	Managed Postgres	Local SQLite
Embeddings	Cloud GTE (768d)	Local ONNX (GTE/MiniLM)
Billing	Metered per operation	Free, unlimited
Requires internet	Yes	No
Best for	Teams, production agents	Offline dev, privacy-sensitive

Both modes expose the same 6 core tools with identical parameters and response shapes. Agents don't need to change prompts or workflows when switching between local and remote.

On this page