[FEATURE] API mode for Cursor

[phamleduy04]

What problem or use case are you trying to solve?

I have a dedicated server I want to host cipher on, then use multiple computers to connect to cipher without installing cipher on client machines.

Currently, I hosted cipher successfully on Docker and expose the port in my internal network.

But when I try to curl /mcp based on log cipher-api | 21:01:43 INFO: [API Server] MCP SSE endpoints available at /mcp/sse and /mcp

Got this error

curl http://external:3000/mcp
{"success":false,"error":{"code":"NOT_FOUND","message":"Route GET /mcp not found"},"meta":{"timestamp":"2025-08-05T14:01:58.444Z","requestId":"6e808576-d35f-4003-996a-37a9cc15f893"}}%  

Check the code there is /api/mcp/servers/ endpoint:

curl http://external:3000/api/mcp/servers
{"success":true,"data":{"connected":[{"name":"filesystem","status":"connected","connected":true},{"name":"web_browser","status":"connected","connected":true}],"failed":[{"name":"web_browser","status":"failed","error":"Failed to connect to MCP server: spawn uvx ENOENT","connected":false}],"totalConnected":2,"totalFailed":1},"meta":{"timestamp":"2025-08-05T14:02:56.004Z","requestId":"72b1cf91-e06c-4a5b-983c-6d32709c2239"}}%  

Describe alternatives you've considered

I tried multiple ways to add it to cursor but cursor seems to not recognize mcp server.

Acceptance Criteria

• MCP works in API mode for multiple apps (cursor, windsurf, claude code, etc...) without install cipher locally.

Priority/Impact

• Priority: Low
• Impact: Medium
• Effort Estimate: Medium

---

If you find this feature request or enhancement useful, make sure to add a 👍 to the issue

[RyanNg1403]

thanks for your feedback @phamleduy04 , please checkout PR #183 to see if this issue has been fixed for you!

[phamleduy04]

@RyanNg1403 can you public the github package so I can pull it?

https://github.com/orgs/campfirein/packages -> choose cipher -> package settings -> set it public and you might want to link the package to this repo

[phamleduy04]

just build it myself and run it, i got an error from cursor

Docker compose

Checking the logs I saw:

cipher-api  | 15:00:18 INFO: [API Server] Using API prefix: '/""'
cipher-api  | 15:00:18 INFO: [API Server] Setting up MCP server with transport type: sse
cipher-api  | 15:00:18 INFO: [API Server] MCP server mode: default
cipher-api  | 15:00:18 INFO: [MCP Handler] Initializing MCP server with agent capabilities (mode: default)
cipher-api  | 15:00:18 INFO: [MCP Handler] Registering 1 MCP tools: ask_cipher
cipher-api  | 15:00:18 INFO: [MCP Handler] MCP server initialized successfully (mode: default)
cipher-api  | 15:00:18 INFO: [MCP Handler] Agent is now available as MCP server for external clients
cipher-api  | 15:00:18 INFO: [API Server] MCP SSE (GET /""/mcp/sse) and POST (/""/mcp?sessionId=...) routes registered.
cipher-api  | 15:00:18 INFO: [API Server] MCP server setup completed successfully
cipher-api  | 15:00:18 INFO: Starting WebSocket event subscription
cipher-api  | 15:00:18 INFO: WebSocket event subscriptions established
cipher-api  | 15:00:18 INFO: [API Server] WebSocket server initialized
cipher-api  | 15:00:18 INFO: API Server started on 0.0.0.0:3000
cipher-api  | 15:00:18 INFO: [API Server] MCP SSE endpoints available at /""/mcp/sse and /""/mcp

It seems like it register the empty string as a API prefix?

[RyanNg1403]

@phamleduy04 sorry for that annoying bug, the environment variable CIPHER_API_PREFIX treats "" as an empty string rather than an empty prefix, which. I'll fix that in a minute
You can also set the prefix via the flag --api-prefix like in here, which is behaving correctly now.
If both are set, CIPHER_API_PREFIX will take precedence.

[phamleduy04]

It does work after remove CIPHER_API_PREFIX

but cursor still showing issues:

Cursor mcp.json

{
  "mcpServers": {
    "cipher": {
      "transport": {
        "type": "sse",
        "url": "http://external:3000/mcp/sse",
        "postUrl": "http://external:3000/mcp"
      }
    }
  }
}

curl logs

curl http://external:3000/mcp
{"success":false,"error":{"code":"NOT_FOUND","message":"Route GET /mcp not found"},"meta":{"timestamp":"2025-08-06T15:40:57.667Z","requestId":"5a9d2ffe-ac21-4348-909e-8b33b4cf0cf6"}}

curl http://external:3000/mcp/sse
event: endpoint
data: /mcp?sessionId=3afaa053-e157-489b-9440-e95da5125ae9

cipher.yml mcpServers

mcpServers: 
  filesystem:
    type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-filesystem'
      - .

[RyanNg1403]

It does work after remove CIPHER_API_PREFIX

but cursor still showing issues:

Cursor mcp.json

{
"mcpServers": {
"cipher": {
"transport": {
"type": "sse",
"url": "http://external:3000/mcp/sse",
"postUrl": "http://external:3000/mcp"
}
}
}
}
curl logs

curl http://external:3000/mcp
{"success":false,"error":{"code":"NOT_FOUND","message":"Route GET /mcp not found"},"meta":{"timestamp":"2025-08-06T15:40:57.667Z","requestId":"5a9d2ffe-ac21-4348-909e-8b33b4cf0cf6"}}

curl http://external:3000/mcp/sse
event: endpoint
data: /mcp?sessionId=3afaa053-e157-489b-9440-e95da5125ae9

cipher.yml mcpServers

mcpServers:
filesystem:
type: stdio
command: npx
args:
- -y
- '@modelcontextprotocol/server-filesystem'
- .

Did you add --api-prefix "" in your docker compose?

[phamleduy04]

yes,

here is my docker compose

services:
  cipher-api:
    image: ghcr.io/phamleduy04/cipher:latest
    container_name: cipher-api
    networks:
      - proxy
    ports:
      - '3000:3000'
    environment:
      - PORT=3000
      - NODE_ENV=production
      - CIPHER_MULTI_BACKEND=1
      - CIPHER_PG_URL=<removed> # Update with your actual credentials
      - CIPHER_WAL_FLUSH_INTERVAL=5000 # Optional: flush interval in ms
    env_file:
      - .env
    command:
      [
        'sh',
        '-c',
        'node dist/src/app/index.cjs --mode api --port 3000 --host 0.0.0.0 --agent /app/memAgent/cipher.yml --api-prefix "" --mcp-transport-type sse',
      ]
    volumes:
      - ./memAgent:/app/memAgent:ro # Mount custom agent config
      - ./cipher-data:/app/.cipher # Persist application data
    restart: unless-stopped
    healthcheck:
      test:
        [
          'CMD',
          'sh',
          '-c',
          'wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1',
        ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    depends_on:
      - cipher-db
      - cipher-qdrant

[phamleduy04]

But docker logs not saying anything about API prefix.

cipher-api  | 15:39:49 INFO: Loading agent config from /app/memAgent/cipher.yml
cipher-api  | 15:39:49 INFO: MCP Manager: MCPManager initialized
cipher-api  | 15:39:49 INFO: MCP Manager: Initializing 1 servers (0 disabled)
cipher-api  | 15:39:49 INFO: MCP Manager: Connecting to server: filesystem
cipher-api  | 15:39:49 INFO: MCP Manager: Registered client: filesystem
cipher-api  | 15:39:49 INFO: MCP Connection: Connecting to filesystem (stdio)
cipher-api  | Secure MCP Filesystem Server running on stdio
cipher-api  | 15:39:58 INFO: MCP Connection: Successfully connected to filesystem
cipher-api  | 15:39:58 INFO: MCP Manager: Successfully connected to server: filesystem
cipher-api  | Client does not support MCP Roots, using allowed directories set from server args: [ '/app' ]
cipher-api  | 15:39:58 INFO: MCP Manager: Retrieved 0 total prompts
cipher-api  | 15:39:58 INFO: MCP Manager: Retrieved 0 total resources
cipher-api  | 15:39:58 INFO: MCP Manager: Initialization complete
cipher-api  | 15:39:58 INFO: [EMBEDDING:MANAGER] Embedder registered successfully from YAML
cipher-api  | 15:39:58 INFO: Embedding manager initialized successfully
cipher-api  | 15:39:58 INFO: [VectorStoreFactory] Creating vector storage from environment
cipher-api  | 15:39:58 INFO: [VectorStoreManager] Vector storage system connected
cipher-api  | 15:39:58 INFO: [VectorStoreFactory] Vector storage system created successfully
cipher-api  | 15:39:58 INFO: [KG-Factory] Knowledge graph is disabled in environment
cipher-api  | 15:39:58 ERROR: Invalid LLM configuration provided to createContextManager
cipher-api  | 15:39:58 WARN: Failed to initialize LLM service
cipher-api  | 15:39:58 INFO: InternalToolRegistry: Initializing...
cipher-api  | 15:39:58 INFO: InternalToolRegistry: Initialized successfully
cipher-api  | 15:39:58 INFO: Internal tools registration completed
cipher-api  | 15:39:58 INFO: SessionManager: Initializing persistence storage...
cipher-api  | 15:39:58 INFO: [StorageManager] Initialized with configuration
cipher-api  | 15:39:58 INFO: [StorageManager] Starting connection attempt 1
cipher-api  | 15:39:58 INFO: InMemoryBackend connected
cipher-api  | 15:39:58 INFO: [StorageManager:Cache] Connected successfully
cipher-api  | 15:39:58 INFO: Connecting to PostgreSQL database
cipher-api  | 15:40:03 ERROR: Failed to connect to PostgreSQL database
cipher-api  | 15:40:03 ERROR: Failed to connect to database backend
cipher-api  | 15:40:03 WARN: [StorageManager:Database] Primary backend failed, attempting fallback to in-memory
cipher-api  | 15:40:03 INFO: InMemoryBackend connected
cipher-api  | 15:40:03 INFO: [StorageManager:Database] Successfully connected to fallback backend
cipher-api  | 15:40:03 INFO: [StorageManager] Storage system connected
cipher-api  | 15:40:03 INFO: SessionManager: PostgreSQL persistence storage initialized successfully
cipher-api  | 15:40:03 INFO: SessionManager: Storage initialized with database backend: in-memory
cipher-api  | 15:40:03 INFO: Starting API server on 0.0.0.0:3000
cipher-api  | 15:40:03 INFO: [API Server] Setting up MCP server with transport type: sse
cipher-api  | 15:40:03 INFO: [API Server] MCP server mode: default
cipher-api  | 15:40:03 INFO: [MCP Handler] Initializing MCP server with agent capabilities (mode: default)
cipher-api  | 15:40:03 INFO: [MCP Handler] Registering 1 MCP tools: ask_cipher
cipher-api  | 15:40:03 INFO: [MCP Handler] MCP server initialized successfully (mode: default)
cipher-api  | 15:40:03 INFO: [MCP Handler] Agent is now available as MCP server for external clients
cipher-api  | 15:40:03 INFO: [API Server] MCP SSE (GET /mcp/sse) and POST (/mcp?sessionId=...) routes registered.
cipher-api  | 15:40:03 INFO: [API Server] MCP server setup completed successfully
cipher-api  | 15:40:03 INFO: Starting WebSocket event subscription
cipher-api  | 15:40:03 INFO: WebSocket event subscriptions established
cipher-api  | 15:40:03 INFO: [API Server] WebSocket server initialized
cipher-api  | 15:40:03 INFO: API Server started on 0.0.0.0:3000
cipher-api  | 15:40:03 INFO: [API Server] MCP SSE endpoints available at /mcp/sse and /mcp
cipher-api  | 15:40:03 INFO: [API Server] WebSocket server available at ws://0.0.0.0:3000/ws
cipher-api  | 15:40:03 INFO: API server is running and ready to accept requests

[RyanNg1403]

It does work after remove CIPHER_API_PREFIX

but cursor still showing issues:

Cursor mcp.json

{
"mcpServers": {
"cipher": {
"transport": {
"type": "sse",
"url": "http://external:3000/mcp/sse",
"postUrl": "http://external:3000/mcp"
}
}
}
}
curl logs

curl http://external:3000/mcp
{"success":false,"error":{"code":"NOT_FOUND","message":"Route GET /mcp not found"},"meta":{"timestamp":"2025-08-06T15:40:57.667Z","requestId":"5a9d2ffe-ac21-4348-909e-8b33b4cf0cf6"}}

curl http://external:3000/mcp/sse
event: endpoint
data: /mcp?sessionId=3afaa053-e157-489b-9440-e95da5125ae9

cipher.yml mcpServers

mcpServers:
filesystem:
type: stdio
command: npx
args:
- -y
- '@modelcontextprotocol/server-filesystem'
- .

I see the issue, your mcp config should look like this, there is no "transport field, sorry for the inaccurate guide in #183 .

[phamleduy04]

Oh okay, that worked. Thanks

I just following step 6 on your PR.

[RyanNg1403]

Oh okay, that worked. Thanks

I just following step 6 on your PR.

@phamleduy04 thanks for timing responses, really appreciate your time and effort.