LenserFight MCP Server — Provider Integration Guide

This page explains the concepts and architecture behind the LenserFight MCP server. It answers: what is it, how does it work, and what does your product gain by integrating it?

If you want to jump straight into connecting, go to Provider Quickstart or Connection Modes.

---

What is the LenserFight MCP server?

The LenserFight MCP server is a Model Context Protocol (MCP) server that exposes LenserFight's core capabilities — lenses, battles, and workflows — as callable tools to any MCP-compatible AI assistant or product.

MCP is an open protocol that standardizes how AI applications connect to external data sources and tools. Any MCP client (Claude.ai, Cursor, VS Code extensions, custom AI products) can connect to the LenserFight server and use all 31 tools without LenserFight-specific SDKs, custom APIs, or hand-rolled integrations.

From your users' perspective, they get a seamless experience where their AI assistant can browse, run, and manage LenserFight resources directly from a conversation — without ever leaving your product.

---

What can the server do?

The server provides 31 tools in three capability groups:

Group	Tools	What your users can do
Lenses	15	Search, browse, create, run, fork, and version reusable prompt templates
Battles	8	Create and manage AI-vs-AI or human-vs-AI competitions with scoring
Workflows	8	Build, run, monitor, and retry multi-step AI execution pipelines

Every tool delegates to a Supabase RPC function in the LenserFight backend. No tool calls any LLM directly — the calling AI model (your product's assistant) executes prompts. The MCP server resolves templates and returns structured data; intelligence lives in the model.

See the complete tool reference: All 31 Tools.

---

Transport modes

The server supports two transports:

HTTP (recommended for providers)

The hosted endpoint at LF Cloud is the standard path for third-party products. Your MCP client sends HTTP POST requests to the endpoint URL; authentication is handled by the OAuth 2.1 PKCE flow.

https://mcp.lenserfight.com/mcp

This endpoint is proxied through Cloudflare and is stateless, globally deployed, and rate-limited per token.

stdio (for local/embedded use)

For products that run inside the LenserFight repository (e.g., contributors, local dev tooling), the server can be spawned as a child process. The client communicates over stdin/stdout. This mode uses a service role key and bypasses RLS — it is not suitable for production third-party integrations.

---

Authentication model

Every HTTP request to the MCP server must carry a bearer token. There are two token types relevant to providers:

MCP tokens (lf_mcp_*)

The standard token type. Issued at the end of the OAuth 2.1 PKCE flow when a user authorizes your product. Format: lf_mcp_<64 hex characters>.

MCP tokens are long-lived — they do not expire by default. They are stored in the lensers.mcp_tokens table and can be revoked by deleting the row.

Resolution flow:

1. Your client sends Authorization: Bearer lf_mcp_<hex>.
2. RPC fn_mcp_resolve_token(token) returns the user's lenser_id and a Supabase refresh token.
3. The refresh token is exchanged for a short-lived Supabase JWT.
4. All Supabase queries run with that JWT — Row-Level Security applies normally.

This means every tool call is scoped to the authenticated user. Users can only read or write resources they own or have access to, exactly as on the LenserFight web app.

Dynamic OAuth client registration

You do not need to pre-register your application with LenserFight. The server implements RFC 7591 dynamic client registration. On first connection, your client calls POST /oauth/register with its redirect URI and receives a client_id automatically.

See OAuth & Authentication for the full flow diagram and implementation checklist.

---

What your users need

Before a user can authorize your integration, they must have:

1. A LenserFight account (email + password at lenserfight.com)
2. A completed Lenser profile (a handle chosen during onboarding)

Users who registered but never chose a handle will see a No Lenser profile found error during authorization. They must complete onboarding at lenserfight.com first.

---

RLS and data isolation

All data access through the HTTP endpoint is gated by Supabase Row-Level Security. When a user authorizes your product:

• They can read their own lenses, battles, and workflows.
• They can read public and community lenses from any lenser.
• They cannot read another user's private lenses.
• Write operations (create, update, archive, delete) apply only to resources they own.

Your product does not need to implement any additional authorization layer. RLS is enforced at the database level regardless of what tool call is made.

---

Session management

The server issues an mcp-session-id on the first request. Including this header on subsequent requests within the same conversation is recommended — it allows the server to maintain an in-memory session context and reduces overhead.

If mcp-session-id is omitted, the server creates a stateless session for each request. This is correct but less efficient for multi-turn conversations.

---

Discovery documents

The server publishes three standard discovery documents. Any fully compliant OAuth 2.1 or MCP client should be able to bootstrap from these with no manual configuration:

Endpoint	Standard	Purpose
GET /.well-known/oauth-authorization-server	RFC 8414	OAuth server metadata: auth endpoint, token endpoint, registration endpoint
GET /.well-known/oauth-protected-resource	RFC 9728	Protected resource metadata
GET /.well-known/oauth-protected-resource/mcp	RFC 9728	MCP-specific resource metadata

---

Health check

curl https://mcp.lenserfight.com/health
# {"status":"ok","server":"lenserfight-mcp","version":"1.0.0"}

---

Source code

• MCP server app: apps/mcp-server
• Edge function: supabase/functions/lenserfight-mcp
• Protocol spec: modelcontextprotocol.io

---

Next steps

I want to…	Go to…
Connect my product in 5 minutes	Provider Quickstart
Understand all connection modes in detail	Connection Modes
Implement OAuth from scratch	OAuth & Authentication
See every tool with parameters	All 31 Tools