MCP

Security: To verify the container’s authenticity and inspect its SBOM, see the Attestation & Verification Guide.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how AI assistants communicate with data sources and tools. The Subnoto MCP Server implements this protocol to allow AI assistants like Claude Desktop and Cursor to interact with Subnoto’s signature services.

Supported AI Tools

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
    "mcpServers": {
        "subnoto": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "MCP_TRANSPORT",
                "-e",
                "API_ACCESS_KEY",
                "-e",
                "API_SECRET_KEY",
                "subnoto/mcp-server:latest"
            ],
            "env": {
                "MCP_TRANSPORT": "stdio",
                "API_ACCESS_KEY": "your_access_key_here",
                "API_SECRET_KEY": "your_secret_key_here"
            }
        }
    }
}

Cursor IDE

Add to your Cursor MCP configuration (~/.cursor/mcp.json):

{
    "mcpServers": {
        "subnoto": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "MCP_TRANSPORT",
                "-e",
                "API_ACCESS_KEY",
                "-e",
                "API_SECRET_KEY",
                "subnoto/mcp-server:latest"
            ],
            "env": {
                "MCP_TRANSPORT": "stdio",
                "API_ACCESS_KEY": "your_access_key_here",
                "API_SECRET_KEY": "your_secret_key_here"
            }
        }
    }
}

Using the Container

Stdio Transport (for AI Assistants)

The stdio transport is designed for integration with AI assistants like Claude Desktop and Cursor:

docker run -i --rm \
  -e MCP_TRANSPORT=stdio \
  -e API_ACCESS_KEY=your_access_key_here \
  -e API_SECRET_KEY=your_secret_key_here \
  subnoto/mcp-server:latest

Note: This mode is interactive and expects MCP protocol messages on stdin. It’s meant to be used by AI tools, not directly by users.

HTTP Transport (for Web Applications)

For web-based integrations, use the HTTP transport:

docker run -p 8080:8080 --rm \
  -e API_ACCESS_KEY=your_access_key_here \
  -e API_SECRET_KEY=your_secret_key_here \
  subnoto/mcp-server:latest

The MCP server will be available at http://localhost:8080/mcp.

Mac users (Apple Silicon): If you encounter connection issues, explicitly bind to localhost and specify the platform:

docker run --platform linux/amd64 -p 127.0.0.1:8080:8080 --rm \
  -e API_ACCESS_KEY=your_access_key_here \
  -e API_SECRET_KEY=your_secret_key_here \
  subnoto/mcp-server:latest

Authentication

The MCP server supports two authentication methods:

API Keys — Static access key + secret key pair. See Create API keys.
SPIFFE Agent Auth — Short-lived JWT SVIDs from your SPIRE infrastructure. See Agent Authentication for setup and configuration, including Workload API integration for automatic token rotation.

Available Tools

The MCP server automatically exposes all Subnoto public API endpoints as MCP tools. Common tools include:

workspace_list - List all workspaces
utils_whoami - Get authenticated user information

contact_list - List contacts in a workspace
contact_get - Get a specific contact
contact_create - Create new contacts
contact_update - Update contact information
contact_delete - Delete contacts

template_list - List available templates

envelope_create - Create a new envelope
envelope_create-from-template - Create an envelope from a template
envelope_get - Get envelope details
envelope_add-recipients - Add recipients to an envelope
envelope_delete-recipients - Remove recipients from an envelope
envelope_send - Send an envelope to recipients
envelope_get-document - Download a document from an envelope
envelope_get-proof - Download the proof document for a completed envelope
envelope_complete-document-upload - Complete the document upload process

Environment Variables

The MCP server supports the following environment variables:

Variable	Description	Default	Required
`MCP_TRANSPORT`	Transport mode: `stdio` or `http`	`http`	No
`API_ACCESS_KEY`	Subnoto API access key	-	Yes*
`API_SECRET_KEY`	Subnoto API secret key	-	Yes*
`SPIFFE_ENDPOINT_SOCKET`	Path to SPIRE Workload API Unix socket	-	No*
`SPIFFE_JWT_SVID`	Static JWT SVID string	-	No*
`SPIFFE_JWT_SVID_PATH`	Path to a file containing a JWT SVID	-	No*
`SPIFFE_AUDIENCE`	Comma-separated JWT audience values	`subnoto.com`	No
`API_BASE_URL`	Subnoto API base URL	`https://enclave.subnoto.com`	No
`DISABLE_ATTESTATION`	Disable attestation verification	`false`	No
`ATTESTATION_PUBLIC_KEYS`	Base64-encoded attestation public keys	-	No
`OPENAPI_PATH`	Path to OpenAPI schema	`/app/public-openapi.json`	No

* Provide either API_ACCESS_KEY+API_SECRET_KEY or one of the SPIFFE options. Priority: SPIFFE_ENDPOINT_SOCKET > SPIFFE_JWT_SVID > SPIFFE_JWT_SVID_PATH > API keys.

Example Usage with AI Assistants

Once configured, you can interact with the MCP server through your AI assistant. For example, in Claude Desktop or Cursor:

User: “List all my signature templates”

AI Assistant: Uses the template_list tool to fetch templates

User: “Create an envelope from the NDA template for [email protected]”

AI Assistant: Uses envelope_create-from-template and envelope_add-recipients tools

User: “Send the envelope”

AI Assistant: Uses the envelope_send tool

Troubleshooting

Next Steps

Explore the Helm Chart for Kubernetes deployment
Learn about Attestation & Verification for security validation
Visit the API documentation for detailed endpoint information