api MCP server

MCP API

A scalable HTTP API for Model Context Protocol (MCP) servers with secure secret management.

Overview

MCP API addresses a critical limitation in the current MCP server ecosystem: most MCP servers are designed for single-user usage, with secrets (API keys, passwords) stored directly in environment variables. This project enhances security and scalability by:

1. Exposing MCP servers via a unified HTTP API
2. Abstracting secret handling through secure encryption
3. Supporting multi-user access to the same MCP server instances
4. Providing package management for easy installation and configuration of MCP servers

Instead of embedding sensitive credentials in environment variables, MCP API stores them encrypted in MongoDB and retrieves/decrypts them as needed for specific tool operations.

Features

• Multi-user Support: Multiple users can access the same MCP server instances with their own credentials
• Secure Secret Management: All sensitive information is stored encrypted in MongoDB
• User-specific Secret Storage: Each user's secrets are isolated and encrypted separately
• Package Management: Simplified installation and configuration of MCP server packages
• HTTP API: Simple REST API for accessing MCP tools and managing secrets
• Streamable HTTP Transport: First-class support for streamable_http MCP servers with optional SSE fallback
• Session Persistence: HTTP session IDs are persisted and resumed across process restarts
• OAuth Token Refresh: Streamable HTTP servers can refresh OAuth tokens automatically via stored refresh tokens
• Containerized Deployment: Docker and Docker Compose support for easy deployment

Architecture

MCP API acts as a proxy between clients and MCP servers:

1. Client Requests: Applications send requests to the HTTP API
2. Secret Management: The API retrieves and decrypts user-specific secrets as needed
3. Package Management: The API handles installation, configuration, and lifecycle of MCP server packages
4. Transport Selection: Each server uses either stdio or Streamable HTTP transport based on configuration
5. MCP Server Communication: The API communicates with MCP servers using the Model Context Protocol
6. Response Handling: Results from MCP servers are returned to clients

The system uses AES-256-GCM encryption for all stored secrets, with a separate encryption key for each deployment.

Installation

Prerequisites

• Node.js 20 or higher
• MongoDB
• MCP server implementations you wish to expose

Setup

1. Clone the repository:

   git clone https://github.com/missionsquad/mcp-api.git
   cd mcp-api
   

2. Install dependencies:

   yarn install
   

3. Create a .env file based on the example:

   cp example.env .env
   

4. Configure your environment variables:

   PORT=8080
   MONGO_USER=username
   MONGO_PASS=password
   MONGO_HOST=localhost:27017
   MONGO_DBNAME=mcp
   SECRETS_KEY=your-random-key
   SECRETS_DBNAME=secrets
   PYTHON_BIN=/usr/bin/python3
   PYTHON_VENV_DIR=packages/python
   PIP_INDEX_URL=
   PIP_EXTRA_INDEX_URL=
   

   The optional Comms Management service-HMAC profile uses one additional environment variable:

   MSQ_COMMS_MCP_HMAC_KEY_FILE=/absolute/path/to/a/mounted/keyring.json
   

   This value is an absolute secret-file path, not key material. The file must be a regular, non-symlink JSON file with mode 0400 or 0440 and the closed SymmetricKeyring shape used by the Comms Agent deployment contract. Do not reuse SECRETS_KEY, a user secret, an OAuth token, or another Mission Squad service keyring.

5. Build the project:

   yarn build
   

6. Start the server:

   yarn start
   

Docker Deployment

Using Docker Compose

1. Configure your .env file as described above
2. Run with Docker Compose:

   docker-compose up -d
   

3. The container image includes Python 3.13 and sets PYTHON_BIN=/usr/local/bin/python3.13 by default for Python MCP package installs.

Building the Docker Image

docker build -t mcp-api .
docker run -p 8080:8080 --env-file .env mcp-api

For Python MCP servers that require Python 3.13+ (for example klaviyo-mcp-server), do not override PYTHON_BIN to an older interpreter in container deployments.

API Reference

Comms Management service-HMAC profile

The V1 service-HMAC transport is limited to one platform-owned Streamable HTTP profile. Register it through the existing server-management API with these non-secret fields (the name remains the caller's stable platform server identifier):

{
  "name": "comms-management",
  "source": "platform",
  "transportType": "streamable_http",
  "authMode": "service_hmac",
  "serviceHmacProfile": "comms_management",
  "url": "https://comms-management:8080/internal/mcp"
}

The combination is closed. It cannot be selected by an external or user-installed server, stdio transport, another URL/profile, configured query or fragment, static headers, shared session ID, OAuth configuration, or external secret fields. Server responses may include the non-secret serviceHmacProfile; they never include the key-file path, key bytes, per-request authentication headers, timestamp, nonce, or signature.

If the environment variable is absent, the keyring is invalid/out of its active window, or a reload fails validation, only this profile is unavailable. Its connection attempt returns a typed service-unavailable error and it does not claim a connected state; /healthz and all unrelated stdio, unauthenticated HTTP, and OAuth servers remain operational.

Send SIGHUP after atomically replacing the mounted keyring file. A completely valid candidate becomes active for the next outbound request. An invalid candidate leaves the prior ring in memory only for later recovery but disables signing until a subsequent valid reload.

Package Management

Install an MCP Package

POST /packages/install

Node.js stdio request body:

{
  "name": "package-name",
  "version": "1.0.0",
  "serverName": "unique-server-name",
  "transportType": "stdio",
  "command": "node",
  "args": ["--option1", "--option2"],
  "env": {
    "NODE_ENV": "production"
  },
  "secretName": "API_KEY",
  "enabled": true,
  "failOnWarning": false
}

Field	Type	Required	Default	Description
name	string	Yes	—	npm package name
version	string	No	"latest"	Package version to install
serverName	string	Yes	—	Unique MCP server identifier
transportType	string	No	"stdio"	"stdio" or "streamable_http"
command	string	No	Auto-detected	Command to start the server. If omitted, resolved from the package's bin or main field
args	string[]	No	[]	Command-line arguments
env	object	No	{}	Environment variables for the server process
secretName	string	No	—	Secret name to associate with this server
enabled	boolean	No	true	Whether to start the server after installation
failOnWarning	boolean	No	false	Fail installation if npm emits warnings

Streamable HTTP install example:

{
  "name": "package-name",
  "version": "1.0.0",
  "serverName": "remote-http-server",
  "transportType": "streamable_http",
  "url": "https://example.com/mcp",
  "headers": {
    "X-Custom-Header": "value"
  },
  "enabled": true
}

Additional fields for streamable_http:

Field	Type	Required	Description
url	string	Yes	The MCP HTTP endpoint
headers	object	No	Static HTTP headers to send with requests
sessionId	string	No	Session ID to resume a previous session
reconnectionOptions	object	No	SSE reconnection settings (see Server Management)

Python stdio install example:

{
  "name": "my-python-mcp",
  "serverName": "python-mcp",
  "runtime": "python",
  "pythonModule": "my_mcp_server",
  "pythonArgs": ["--port", "0"],
  "enabled": true
}

Python packages with a console script entry point (no __main__.py) require the command field to point to the console script binary installed in the venv. When command is provided, pythonModule is still required for metadata purposes but is not used to build the run command:

{
  "name": "klaviyo-mcp-server",
  "serverName": "klaviyo",
  "runtime": "python",
  "pythonModule": "klaviyo_mcp_server",
  "command": "/app/packages/python/klaviyo/bin/klaviyo-mcp-server",
  "pipDependencies": ["fastmcp<3"],
  "env": {
    "PRIVATE_API_KEY": "your-api-key",
    "READ_ONLY": "false",
    "ALLOW_USER_GENERATED_CONTENT": "false"
  }
}

Additional fields for runtime: "python":

Field	Type	Required	Description
runtime	string	Yes	Must be "python"
pythonModule	string	Yes	Python module name (e.g. my_mcp_server). Used with python -m unless command is provided
pythonArgs	string[]	No	Additional arguments passed after the module name
command	string	No	Override the default python -m <module> command. Use for packages that expose a console script entry point instead of __main__.py
args	string[]	No	Arguments for the command when command is provided (replaces pythonArgs)
pipDependencies	string[]	No	Additional pip specs installed alongside the main package (e.g. ["fastmcp<3", "requests>=2.28"]). Persisted and reused during upgrades
pipIndexUrl	string	No	Custom PyPI index URL for pip
pipExtraIndexUrl	string	No	Additional PyPI index URL for pip

Python install behavior:

• If transportType is omitted, the API defaults to "stdio". Python runtime only supports "stdio".
• A virtual environment is created at packages/python/<serverName> (or PYTHON_VENV_DIR/<serverName> if configured).
• Without command: the server runs as <venv>/bin/python -u -m <pythonModule> [pythonArgs...]
• With command: the server runs as <command> [args...] with the venv environment variables set.
• pipDependencies are installed in the same pip install invocation as the main package.
• pipIndexUrl, pipExtraIndexUrl, and pipDependencies are persisted on the package record and reused for upgrades and update checks.

List Installed Packages

GET /packages

Response includes version information for each package:

{
  "success": true,
  "packages": [
    {
      "name": "package-name",
      "version": "1.0.0",
      "latestVersion": "1.1.0",
      "updateAvailable": true,
      "installPath": "/path/to/package",
      "status": "installed",
      "installed": "2025-03-01T12:00:00Z",
      "lastUpgraded": "2025-03-01T12:00:00Z",
      "mcpServerId": "server-name",
      "enabled": true
    }
  ]
}

Optional query parameters:

• checkUpdates=true - Check for updates before returning package information

Get Package by Name

GET /packages/by-name/:name

Get Package by Server ID

GET /packages/by-id/:name

Both endpoints return version information and support the checkUpdates=true query parameter.

Uninstall a Package

DELETE /packages/:name

Removes the package files, stops the associated MCP server, and deletes the server configuration.

Enable a Package

PUT /packages/:name/enable

Enables a previously disabled package and starts its associated MCP server.

Disable a Package

PUT /packages/:name/disable

Disables a package and stops its associated MCP server without removing it.

Check for Package Updates

GET /packages/updates

Optional query parameters:

• name=server-name - Check for updates for a specific package

Response:

{
  "success": true,
  "updates": [
    {
      "serverName": "server-name",
      "currentVersion": "1.0.0",
      "latestVersion": "1.1.0",
      "updateAvailable": true
    }
  ]
}

Upgrade a Package

PUT /packages/:name/upgrade

Request body (optional):

{
  "version": "1.1.0" // Optional, defaults to latest version
}

Response:

{
  "success": true,
  "package": {
    // Updated package information
  },
  "server": {
    // Updated server information
  }
}

Upgrades work for both stdio and streamable_http servers. Streamable HTTP upgrades preserve url, headers, sessionId, and reconnectionOptions and do not attempt stdio command resolution.

Upgrade All Packages

PUT /packages/upgrade-all

Response:

{
  "success": true,
  "results": [
    {
      "serverName": "server-name",
      "success": true
    },
    {
      "serverName": "another-server",
      "success": false,
      "error": "Error message"
    }
  ]
}

MCP Tool Operations

Note: The username parameter is optional in all API endpoints. If omitted, "default" will be used. This allows single users to use the API without specifying a username while still benefiting from encrypted secret storage.

List Available MCP Tools

GET /mcp/tools

Returns a list of all available tools across all registered MCP servers, including their names, descriptions, and input schemas.

Response format:

{
  "success": true,
  "tools": [
    {
      "server-name": [
        {
          "name": "tool-name",
          "description": "A human-readable description of what the tool does",
          "inputSchema": {
            "type": "object",
            "properties": {
              "param1": {
                "type": "string",
                "description": "Description of parameter 1"
              },
              "param2": {
                "type": "number",
                "description": "Description of parameter 2"
              },
              "param3": {
                "type": "object",
                "properties": {
                  "nestedParam": {
                    "type": "string"
                  }
                }
              }
            },
            "required": ["param1"]
          }
        }
      ]
    }
  ]
}

The response structure contains:

• success: Boolean indicating if the request was successful
• tools: An array of objects, each containing a server name as the key and an array of tool definitions as the value
  • Each tool definition includes:
    • name: The name of the tool (used when calling the tool)
    • description: A human-readable description of the tool's functionality
    • inputSchema: A JSON Schema object defining the expected parameters for the tool
      • properties: Defines the parameters the tool accepts
      • required: An array of parameter names that are required

This endpoint is useful for discovering what tools are available and understanding their input requirements before making tool calls.

Call an MCP Tool

POST /mcp/tool/call

Executes a tool on a specified MCP server with the provided arguments.

Request body:

{
  "username": "user123", // Optional, defaults to "default"
  "serverName": "mcp-github",
  "methodName": "create_issue",
  "args": {
    "owner": "username",
    "repo": "repo-name",
    "title": "Issue title",
    "body": "Issue description"
  }
}

Parameters:

• username: (Optional) The username to use for retrieving secrets. Defaults to "default" if not provided.
• serverName: (Required) The name of the MCP server that provides the tool.
• methodName: (Required) The name of the tool to call.
• args: (Required) An object containing the arguments to pass to the tool.

Response format:

{
  "success": true,
  "data": {
    "content": "Tool execution result",
    "contentType": "text/plain"
  }
}

The response structure contains:

• success: Boolean indicating if the request was successful
• data: The result of the tool execution
  • content: The actual result data (can be a string, object, or array)
  • contentType: The MIME type of the content (e.g., "text/plain", "application/json")

Error response:

{
  "success": false,
  "error": "Error message"
}

Secret Handling

A key feature of the /mcp/tool/call endpoint is automatic secret injection:

1. When a tool call is made, the system automatically retrieves any stored secrets for the specified username and server
2. These secrets are merged with the provided arguments before the tool is called
3. This means sensitive information like API keys or passwords don't need to be included in the request payload

For example, if you've previously stored a GitHub token using the /secrets/set endpoint:

{
  "username": "user123",
  "serverName": "mcp-github",
  "secretName": "GITHUB_TOKEN",
  "secretValue": "ghp_xxxxxxxxxxxx"
}

Then when calling a GitHub tool, you don't need to include the token in your request:

{
  "username": "user123",
  "serverName": "mcp-github",
  "methodName": "create_issue",
  "args": {
    "owner": "username",
    "repo": "repo-name",
    "title": "Issue title",
    "body": "Issue description"
  }
}

The system will automatically inject the GITHUB_TOKEN into the arguments before calling the tool.

This approach provides several benefits:

• Clients don't need to manage or expose sensitive credentials in their requests
• Each user can have their own set of secrets for the same MCP servers
• Secrets are stored securely (encrypted) and only decrypted when needed

List Available MCP Servers

GET /mcp/servers

Returns a list of all registered MCP servers with their configuration and status information.

Response format:

{
  "success": true,
  "servers": [
    {
      "name": "mcp-github",
      "transportType": "stdio",
      "command": "./node_modules/@missionsquad/mcp-github/build/index.js",
      "args": ["--port", "3000"],
      "env": {
        "NODE_ENV": "production"
      },
      "status": "connected",
      "enabled": true,
      "toolsList": [
        {
          "name": "create_issue",
          "description": "Creates a new issue in a GitHub repository",
          "inputSchema": {
            "type": "object",
            "properties": {
              "owner": {
                "type": "string",
                "description": "Repository owner"
              },
              "repo": {
                "type": "string",
                "description": "Repository name"
              },
              "title": {
                "type": "string",
                "description": "Issue title"
              },
              "body": {
                "type": "string",
                "description": "Issue body"
              },
              "labels": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Labels to apply to the issue"
              },
              "assignees": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Users to assign to the issue"
              }
            },
            "required": ["owner", "repo", "title"]
          }
        }
      ],
      "logs": []
    }
  ]
}

The response structure contains:

• success: Boolean indicating if the request was successful
• servers: An array of server objects, each containing:
  • name: The unique name of the MCP server
  • command: The command used to start the server
  • args: Command-line arguments passed to the server
  • env: Environment variables set for the server (excluding secrets)
  • url: Streamable HTTP endpoint (streamable_http only)
  • headers: Optional HTTP headers (streamable_http only)
  • sessionId: Optional persisted MCP session ID (streamable_http only)
  • reconnectionOptions: SSE reconnection settings (streamable_http only)
  • status: Current connection status ("connected", "connecting", "disconnected", or "error")
  • enabled: Whether the server is enabled
  • toolsList: Array of tools provided by this server (same format as in /mcp/tools response)
  • logs: Array of captured log messages if the server encountered any issues

This endpoint is useful for monitoring the status of all MCP servers and understanding their configurations.

MCP Server Management

Get a Specific MCP Server

GET /mcp/servers/:name

Retrieves detailed information about a specific MCP server.

Parameters:

• name: (Required) The name of the MCP server to retrieve

Response format:

{
  "success": true,
  "server": {
    "name": "mcp-github",
    "transportType": "stdio",
    "command": "./node_modules/@missionsquad/mcp-github/build/index.js",
    "args": ["--port", "3000"],
    "env": {
      "NODE_ENV": "production"
    },
    "status": "connected",
    "enabled": true,
    "toolsList": [
      {
        "name": "create_issue",
        "description": "Creates a new issue in a GitHub repository",
        "inputSchema": {
          "type": "object",
          "properties": {
            "owner": {
              "type": "string",
              "description": "Repository owner"
            },
            "repo": {
              "type": "string",
              "description": "Repository name"
            },
            "title": {
              "type": "string",
              "description": "Issue title"
            },
            "body": {
              "type": "string",
              "description": "Issue body"
            },
            "labels": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Labels to apply to the issue"
            },
            "assignees": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Users to assign to the issue"
            }
          },
          "required": ["owner", "repo", "title"]
        }
      }
    ],
    "logs": []
  }
}

Error response (server not found):

{
  "success": false,
  "error": "Server mcp-github not found"
}