🔌 Lensa

One local MCP server for app connectors and reusable operational skills.

Lensa lets an MCP client use multiple application APIs through one configurable gateway. Connectors provide focused, typed tools; skills describe workflows that combine those tools. Users enable only the connectors, tools, and skills they need.

Work in progress (0.1.0). Lensa is under active development and currently intended for local, single-user use. It is not yet a hosted or authenticated service.

🔌 What is included

Connector	Coverage
Clerk	Users, sessions, organizations, memberships, invitations, domains, enterprise connections, and access actions
Vercel	Projects, deployments and logs, environment variables, domains, DNS, team membership, and deployment actions

These are the first bundled connectors, not a closed catalog. To add another application or extend an existing connector, start with Adding a connector. You can also propose connector coverage through GitHub issues. Provider-specific documentation is collected under Connectors.

Lensa also bundles discoverable workflows for Clerk login and access investigations, Vercel deployment diagnosis and incident triage, and access or production changes. See Skills for the catalog and authoring model.

🚀 Quick start

You need Docker and credentials for each enabled connector. ChatGPT additionally requires an OpenAI Secure MCP Tunnel ID and runtime key.

git clone https://github.com/mitrotasios/lensa-mcp.git
cd lensa-mcp

cp secrets/connector_credentials.yaml.example secrets/connector_credentials.yaml

Then:

1. Put connector credentials in secrets/connector_credentials.yaml.
2. Enable only the required connectors and tools in config/lensa.yaml.
3. Start Lensa for a local MCP client:

Review the default tool selection. The checked-in configuration enables all current tools, including confirmation-gated write tools. To start with nothing exposed, use config/lensa.disabled.example.yaml and add only the connectors, tools, and skills you want.

docker compose up --build

For ChatGPT, create the tunnel-specific local files:

cp .env.example .env
cp secrets/openai_tunnel_api_key.example secrets/openai_tunnel_api_key

Create a tunnel in OpenAI Platform, set its OPENAI_TUNNEL_ID in .env, replace the contents of secrets/openai_tunnel_api_key with the tunnel runtime key, and start Lensa with the optional chatgpt profile:

docker compose --profile chatgpt up --build

The getting-started guide covers tunnel creation, required permissions, workspace association, and troubleshooting.

Check readiness at http://127.0.0.1:8000/readyz and capabilities at http://127.0.0.1:8000/status. The local MCP endpoint is http://127.0.0.1:8000/mcp.

The getting-started guide covers credential references, tool and skill selection, ChatGPT tunnel setup, other local MCP clients, and troubleshooting surfaces.

⚙️ How it works

MCP client
   │
   ▼
Lensa MCP server
   ├── enabled connector tools ──▶ external provider APIs
   ├── eligible workflow skills
   └── connector-scoped credentials

At startup, Lensa validates configured credentials, builds the explicitly registered connectors, and registers only enabled tools with the MCP server. MCP clients discover those tools through the standard MCP tool-list operation. Skills are returned dynamically only when all their connector and tool dependencies are available.

Some write tools provide a read-only preflight and require a confirmation argument before changing external state. This behavior is not an authorization boundary and should not be treated as a complete security system.

Read Architecture and security for the runtime boundaries, credential model, and current limitations.

📚 Documentation

• Getting started — installation, configuration, tunnel setup, and client connection.
• Connectors — available integrations, authentication, tools, and provider-specific behavior.
• Skills — discovery, eligibility, bundled workflows, and authoring.
• Adding a connector — connector structure, tool creation, registration, safety, and tests.
• Architecture and security — execution flow, trust boundaries, and operational defaults.

🗺️ Roadmap

Near-term direction includes:

• OAuth-based authentication and connector authorization flows;
• multiple users with isolated identities, credentials, and connector installations;
• permissions controlling which connectors, tools, and actions each user can access;
• more connectors, broader tool coverage, and additional reusable skills; and
• auditability and deployment hardening for use beyond local evaluation.

These items describe the intended direction, not functionality available in the current release.

🛠️ Development

Lensa requires Python 3.13 and uv.

uv sync --locked --extra dev
uv run --extra dev ruff check .
uv run --extra dev mypy
uv run --extra dev pytest

Tests mock provider HTTP and do not require live credentials. Connector contributions should use documented provider APIs, narrow typed operations, curated outputs, truthful safety metadata, and explicit registration. Start with Adding a connector; repository-specific guidance for coding agents is in AGENTS.md.

Connector requests and contributions are welcome through GitHub issues.

📄 License

Lensa is licensed under the Apache License 2.0.