# 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:

```bash
# 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`.