MCP Server (Model Context Protocol)
Relevant source files
The following files were used as context for generating this wiki page:
The SecretForge MCP Server is a specialized integration layer designed to expose SecretForge's security and secret management capabilities to AI assistants like Claude Code and other Model Context Protocol-compatible tools. By acting as a bridge between the AI and the SecretForge core API, it allows LLM-based agents to perform complex tasks such as project dependency analysis, secret provisioning, and security auditing directly within the developer's workflow.
Sources: packages/mcp-server/README.md:1-10, README.md:15-30
This server enables a "Natural Language Interface" where users can prompt an AI to "Analyze my project and detect required API keys" or "Provision a Stripe API key for production," with the MCP server translating these intents into executable actions against the SecretForge backend.
Sources: README.md:43-45, packages/mcp-server/README.md:95-103
Architecture and Data Flow
The MCP Server is built using the @modelcontextprotocol/sdk and operates over a Standard Input/Output (stdio) transport layer. It acts as a client-facing interface that communicates with the Cloudflare-based SecretForge API to perform operations.
The diagram above illustrates the communication path from an AI client through the MCP server to the SecretForge infrastructure.
Sources: packages/mcp-server/src/index.ts:1-35, README.md:32-41
Server Lifecycle and Transport
The server initializes using the StdioServerTransport and connects to the main server instance. It handles JSON-RPC requests for listing tools, listing prompts, and executing specific tool calls or prompt workflows.
Sources: packages/mcp-server/src/index.ts:286-302
Core Capabilities: Tools
Tools represent the functional actions the AI can perform. Each tool is defined with a schema (using Zod for validation) and an execution handler that often involves a fetch call to the local or remote SecretForge API (defaulting to http://localhost:8787).
Sources: packages/mcp-server/src/index.ts:37-160, packages/mcp-server/README.md:20-25
Available Tools Table
| Tool Name | Description | Key Arguments |
|---|---|---|
analyze_project | Scans a directory for package.json to detect required services. | projectPath |
create_secret | Provisions a new API key for a specified service and environment. | service, environment, scopes |
rotate_secret | Triggers a rotation for an existing secret ID. | secretId |
search_documentation | Semantic search across service API documentation. | service, query |
validate_security | Checks a secret against frameworks like SOC2, GDPR, or HIPAA. | secretId, framework |
Sources: packages/mcp-server/src/index.ts:54-124, packages/mcp-server/README.md:27-80
Project Analysis Logic
The analyze_project tool uses a detectServices helper to map dependencies found in package.json to known services like Stripe, OpenAI, AWS, Supabase, and Anthropic.
This flow depicts the logic for identifying which cloud services a project requires based on its library dependencies.
Sources: packages/mcp-server/src/index.ts:241-274
AI Prompts and Workflows
Unlike atomic tools, prompts provide pre-defined templates that guide the AI in conducting structured workflows. These are retrieved via ListPromptsRequestSchema and executed via GetPromptRequestSchema.
Sources: packages/mcp-server/src/index.ts:202-215
Provisioning and Auditing
provision_api_key: An intelligent workflow for provisioning. It takes aserviceand an optionalcontextobject to construct a message that the AI uses to start the secret creation process.security_audit: A comprehensive audit workflow that accepts ascope(project, organization, or service) to analyze current security postures.
Sources: packages/mcp-server/src/index.ts:206-224, packages/mcp-server/README.md:82-93
Configuration and Deployment
The MCP server is packaged as a Node.js module and can be installed globally or run via npx.
Environment Variables
The server relies on the SECRETFORGE_API variable to know where to send its requests.
| Variable | Description | Default |
|---|---|---|
SECRETFORGE_API | The base URL for the SecretForge Workers API. | http://localhost:8787 |
Sources: packages/mcp-server/README.md:105-107, WARP.md:55-58
Integration with Claude
To use the server with Claude Code, it must be configured in the .claude/mcp.json file.
{
"mcpServers": {
"secretforge": {
"command": "secretforge-mcp",
"args": []
}
}
}
Sources: packages/mcp-server/README.md:13-25, scripts/launch.sh:160-185
Development and Testing
The package includes several scripts for lifecycle management, utilizing tsup for building and vitest for testing.
- Build:
pnpm build(Usestscas defined inpackage.jsonortsupin automated scripts). - Development:
tsx watch src/index.tsallows for real-time testing of changes. - Inspector: Testing can be performed using the MCP Inspector:
npx @modelcontextprotocol/inspector secretforge-mcp.
Sources: packages/mcp-server/package.json:9-24, packages/mcp-server/README.md:111-125, scripts/launch.sh:150-160
Summary
The SecretForge MCP Server serves as the critical "intelligence interface" for the project. By implementing the Model Context Protocol, it transforms static secret management into an interactive, AI-driven experience. Developers can leverage their existing AI tools to automatically detect needs, provision credentials securely, and audit their security posture without leaving their development environment.
Sources: packages/mcp-server/README.md:5-10, README.md:47-49