Second Brain OS MCP Server

This package provides a Model Context Protocol (MCP) server for integrating Second Brain OS with Claude Desktop and Claude Code.

Prerequisites

• Node.js v16 or higher
• Claude Desktop application and/or Claude Code CLI
• A valid Second Brain OS account with the Claude MCP feature enabled

Installation

npm install -g secondbrainos-mcp-server

Usage

After installation, run the setup command with your USER_ID and USER_SECRET:

secondbrainos-mcp USER_ID USER_SECRET

This will:

1. Verify your account credentials
2. Confirm you have access to the Claude MCP feature
3. Store credentials securely at ~/.secondbrainos/credentials.json
4. Configure Claude Desktop and Claude Code to use serve mode (credentials read from file, not embedded in config)

Claude Code

To add the server to Claude Code:

claude mcp add secondbrainos-mcp-server -- npx secondbrainos-mcp-server

Or add it to your project's .mcp.json file.

Features

Enhanced OpenAPI Support

The server uses @samchon/openapi library for robust OpenAPI handling, providing:

• Support for all OpenAPI/Swagger versions (v2.0, v3.0, v3.1)
• Automatic schema conversion to a standardized format
• Better handling of complex schemas including references, nullable properties, and union types

Improved Function Execution

• Type-safe function execution with built-in error handling
• Automatic request formatting based on OpenAPI specifications
• Support for complex parameters and nested objects

Prompts

The server exposes four types of MCP prompts, available as slash commands (e.g. /secondbrainos:agent_my_agent):

Start (start_secondbrainos)

• Returns a context document with SBOS terminology, agent architecture, and an index of all available agents and skills with their slash commands
• This is the zero-cost discovery mechanism — Claude can read this prompt to learn what agents and skills are available without calling getAIAgentsSchema or runPromptChain as MCP tools (which would be billed). All discovery data comes from the in-memory cache populated at session init
• Useful for orienting Claude at the start of a session

Skills (Workflows)

• Discovered via runPromptChain on first ListPrompts call, then cached for the session
• Each skill appears with a [Skill] prefix and returns a structured document with skill_id, name, description, and an ordered list of prompts (metadata only, no instructions)
• Supports an optional user_input argument to provide additional context

Agents

• Discovered via getAIAgentsSchema on first ListPrompts call, then cached for the session
• Each agent appears with an [Agent] prefix and returns a structured document containing agent_id, name, description, behaviour_and_instructions, searchMyKnowledge_collection_id, actions (with id, name, description, body_parameters), and workflows (with prompt order and description)
• Supports an optional user_input argument

Features

• Extracted from the features array in the schema.secondbrainos.com response at startup, then cached
• Each feature appears with a [Feature] prefix and returns its guidelines text
• Features have consistent guidelines for all users (not user-specific)
• Supports an optional user_input argument

Knowledge Bases

• Aggregates all searchMyKnowledge_collection_id values from your agents
• Appears as a single [Knowledge Bases] prompt returning an array of collection IDs

Better Error Handling

• Detailed error messages for debugging
• Proper handling of authentication failures, bad requests, and service errors
• Graceful fallback for unexpected errors

Development

Setup

1. Clone the repository:

git clone https://github.com/your-username/secondbrainos-mcp-server.git
cd secondbrainos-mcp-server

2. Install dependencies:

npm install

3. Create a .env file from the example:

cp .env.example .env
# Edit .env with your actual USER_ID and USER_SECRET

Testing the Schema Conversion

To see how your OpenAPI schema is converted to MCP tools:

npm run test-conversion

This will:

• Fetch your OpenAPI schema from Second Brain OS
• Convert it to LLM function calling format
• Display all available functions and their schemas
• Show any conversion errors
• Demonstrate the MCP tool format

Development Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Run the MCP server in development mode
• npm run test-conversion - Test the OpenAPI to MCP conversion
• npm start - Run the compiled server

Project Structure

secondbrainos-mcp-server/
├── src/
│   ├── index.ts           # Main MCP server implementation
│   └── test-conversion.ts # Schema conversion testing utility
├── build/                 # Compiled JavaScript (git-ignored)
├── bin/
│   └── cli.js            # CLI setup script
├── .env.example          # Environment variables template
├── package.json          # Package configuration
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Credentials

Credentials are stored securely at ~/.secondbrainos/credentials.json (created during setup with mode 0o600). The server reads from this file in serve mode. Environment variables USER_ID, USER_SECRET, and API_BASE_URL can override the stored credentials if set.

How It Works

Startup & Session Init

1. Schema Fetching (0 credits): On startup, the server POSTs your user_id to schema.secondbrainos.com and receives your personalized OpenAPI spec along with a features array (consistent guidelines for all users)
2. Schema Conversion: The @samchon/openapi library converts the spec to LLM function calling format. Each API endpoint becomes an MCP tool. Three service paths are discovered from the spec for internal use:
   • runPromptChain — fetches workflows/skills
   • getAIAgentsSchema — fetches agents
   • generateFileUploadGoogleCloudStorageURL — used only when a tool argument contains a local file path
3. MCP server connects via stdio — no API calls yet, no credits spent

Cache Population (on first connection)

4. ListPrompts trigger: Claude Code automatically calls ListPrompts on connect. This is when the first credits are spent:
   • runPromptChain is called with {} → returns all user workflows with prompt metadata (name, order, description)
   • getAIAgentsSchema is called with {include_sensitive_config: true} → returns all user agents with behaviour, knowledge collection ID, actions, and workflows
5. In-memory cache: Both responses are normalized (consistent field names, defaults applied) and sorted (prompts ordered by order field), then stored in memory as cachedWorkflows, cachedAgents, and name-to-ID lookup maps
6. Slash commands exposed: The cached data is surfaced as MCP prompts — /secondbrainos:feature_*, /secondbrainos:skill_*, /secondbrainos:agent_*, /secondbrainos:start_secondbrainos, and /secondbrainos:knowledge_bases

During the Session

7. Slash commands (0 credits): When a user runs a slash command (e.g. /secondbrainos:agent_my_agent), the server returns the full agent/skill definition from cache — no API calls
8. start_secondbrainos (0 credits): Builds a context document from cached agents and workflows — an index of all available slash commands with descriptions, enabling Claude to discover and invoke agents/skills autonomously
9. Tool calls (billed per call): When Claude calls an MCP tool (e.g. runPromptChain with a specific entity/entity_id to fetch prompt instructions, or searchMyKnowledge), the server executes the API call via api.secondbrainos.com with authentication
10. File upload: If a tool argument contains a local file path (e.g. addToMyKnowledge with file_path), the server validates the extension (.txt, .md, .png, .jpg, .jpeg, .gif, .webp, .pdf), uploads the file to GCS via generateFileUploadGoogleCloudStorageURL with the correct MIME type, and replaces the path with the GCS URI before forwarding the API call

Credit Cost

| Event | Credits | |-------|---------| | Schema fetch | 0 | | Session init (ListPrompts) | n workflows + n agents | | Slash commands | 0 (cached) | | start_secondbrainos | 0 (cached) | | Tool calls | Billed per call via service router |

See docs/architecture.md for detailed diagrams.

Troubleshooting

Client doesn't see the server

1. Claude Desktop: Ensure it's completely quit before running setup. Check the configuration file was created at the correct location.
2. Claude Code: Run claude mcp add or check your .mcp.json configuration.
3. Review the logs at the platform-specific location mentioned during setup

Authentication errors

• Verify your USER_ID and USER_SECRET are correct
• Ensure your account has the Claude MCP feature enabled
• Check that your credentials haven't expired

Schema conversion errors

• Run npm run test-conversion to see detailed error messages
• Some complex OpenAPI features may not be supported by LLM function calling
• Check the console output for specific endpoints that failed conversion

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT