owlen/docs/mcp-reference.md

MCP Reference Bundles

Owlen’s MCP configuration guidance now targets the same canonical toolset shipped by leading desktop and IDE clients, without relying on brand-specific heuristics. This document distills the common naming rules, connector categories, and installation patterns you should follow when wiring those tools into Owlen.

Naming Rules

• Tool identifiers must match the regular expression ^[A-Za-z0-9_-]{1,64}$.citeturn11search0
• Avoid dots or spaces in identifiers; use underscores when you need multiword names (sequential_thinking, browser_fetch).
• When multiple servers expose similarly named tools, qualify the call using {server}__{tool} (for example, filesystem__read or browser__request).

Connector Categories

Category	Connector	Capability Highlights	Typical Command Snippet
Core context	filesystem	Mount local directories for read/write access during a chat session.citeturn1search6	npx -y @modelcontextprotocol/server-filesystem <paths…>
Core context	sequential-thinking	Structured problem solving with persistent reasoning chains and Memory Bank integration.citeturn1search0turn1search6	npx -y @modelcontextprotocol/server-sequential-thinking
Core context	fetch	Lightweight HTTP client for REST/JSON retrieval.citeturn1search6	npx -y @kazuph/mcp-fetch
Automation	puppeteer	Headless browser automation (navigation, screenshots, DOM scripting).citeturn1search5turn1search7	npx -y @modelcontextprotocol/server-puppeteer
Automation	browser-tools / devtools	Deep Chrome DevTools integration for inspection and profiling.citeturn1search6	npx -y @modelcontextprotocol/server-browser-tools
Retrieval	brave-search, firecrawl	API-driven web search and scraping for current information (requires API keys).citeturn1search6turn1search8	claude mcp add brave-search … (replace with owlen mcp add brave_search …)
Retrieval	perplexity, tavily, search1api	Aggregated search/QA endpoints with structured responses.citeturn1search8	owlen mcp add tavily -- npx -y @tavily/mcp-server
Observability	sentry, raygun	Incident and crash analytics access for production systems.citeturn1search8	owlen mcp add sentry -- npx -y @sentry/mcp-server
Productivity	notion, slack, stripe, zapier, google_drive	Common SaaS integrations for knowledge bases, messaging, payments, automation, and storage.citeturn1search8	owlen mcp add notion -- npx -y @notion/mcp-server
Data	postgresql, sqlite, qdrant, redis, tinybird	Database and vector-store connectors for analytics and retrieval.citeturn1search8	owlen mcp add postgresql -- npx -y @modelcontextprotocol/server-postgresql
Execution	python, notebook, riza, semgrep	Sandbox code execution, notebook orchestration, security linting.citeturn1search8	owlen mcp add python -- npx -y @modelcontextprotocol/server-python

Tip: Replace any vendor-specific CLI (for example, claude mcp add) with the upcoming owlen mcp add command when working within Owlen. Until that lands, copy the arguments into config.toml directly or wrap them in project scripts—the syntax is intentionally mirrored so the migration is mechanical.

Installation Workflow

1. Plan your bundle. Start with the core context servers (filesystem, sequential-thinking, fetch, puppeteer). Layer in retrieval, observability, productivity, and execution connectors as your project requires.
2. Add each server under [mcp_servers]. Use spec-compliant names and consider grouping them by category inside config.toml.
3. Qualify tool calls. When writing prompts or unit tests, address tools using {server}__{tool} to avoid collisions once you enable multiple servers that expose similar endpoints.
4. Document required secrets. Many SaaS connectors need API keys. Store their environment variables in your preferred secret manager and reference them in the [mcp_servers.<name>.env] table.
5. Run health checks. Each connector listed above includes a health or status endpoint; wire these into your startup scripts so Owlen can surface actionable errors before a chat begins.

Next Steps

• Update config.toml with the reference bundle (see docs/configuration.md).
• Use owlen tools audit to remove or disable any legacy MCP servers that do not meet the naming constraints.
• Track connector-specific onboarding (API keys, OAuth scopes) in team documentation so new contributors can reproduce the setup quickly.

Preset Workflow

Run these helpers after updating Owlen to align your MCP configuration with the reference bundles:

# Install the baseline connectors
owlen tools install standard

# Extend with retrieval and automation
owlen tools install extended

# Switch to the full SaaS bundle (remove anything not in the preset)
owlen tools install full --prune

# Review current configuration against the full preset
owlen tools audit full

Within the TUI the same presets are available via commands such as :tools install standard --prune and :tools audit full.