Installation guide

Find each MCP server and how it runs: stdio, HTTP, a new server per request, or serverless. Keep its existing tools, transport, and MCP SDK version.

Install lsquare with your project's package manager and update its dependency files. For npm:

$ npm install lsquare

• After installing, read node_modules/lsquare/README.md and follow its linked reference for your host. LSquare runs on Node 18+, Cloudflare Workers, and Bun.

TypeScript SDK README

Create the client once per process and share it across your servers. Read the key from the environment; never hardcode or commit it. Import this client wherever you instrument a server.

import { LSquare } from 'lsquare'

export const lsquare = new LSquare({ apiKey: process.env.LSQUARE_KEY })

Request API key

Call instrument() before the server connects or starts serving requests. Use your existing server instance and the shared client.

import { instrument } from 'lsquare/mcp'

instrument(server, lsquare)

Follow the reference's recipe for your host. Pass the relevant options in the same instrument() call:

• New server per request: instrument inside the factory, sharing the client across requests.
• Cloudflare Workers: pass { waitUntil: ctx.waitUntil.bind(ctx) } from the current request. A reused server must resolve the current request's context each time.
• Vercel: import waitUntil from @vercel/functions and pass { waitUntil }.
• AWS Lambda, or Cloud Run without always-on CPU: pass { flushBeforeReply: true } so sending is awaited before replying.
• Long-running HTTP server: call await lsquare.shutdown() in your graceful shutdown handler on SIGTERM.
• Keep a shared client alive across requests and invocations; shut it down only when the process is stopping.

Host setup and shutdown recipes

The LSquare additions are marked below. This example uses MCP SDK 1.x imports; keep the imports and tool registrations your project already uses.

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { LSquare } from 'lsquare'        // ADD THIS
import { instrument } from 'lsquare/mcp' // ADD THIS

const lsquare = new LSquare({ apiKey: process.env.LSQUARE_KEY }) // ADD THIS

const server = new McpServer({ name: 'shop', version: '1.0.0' })
// Keep your existing tool registrations here.

instrument(server, lsquare) // ADD THIS

await server.connect(new StdioServerTransport())

Set LSQUARE_DRY_RUN=1 in the server's environment and start it with your project's usual command. Call one existing tool through your MCP client and confirm [lsquare dry-run] lines appear on stderr. Nothing is sent in dry run. Keep stdout free of logs on stdio servers, then run your project's tests and type checks.

• When ready to send events, remove LSQUARE_DRY_RUN, set LSQUARE_KEY in the server's environment, and restart it.

Run the command for your coding agent from your project directory. It adds the remote LSquare MCP as lsquaremcp. Use the existing connection if it already points to this URL.

$ codex mcp add lsquaremcp --url https://mcp.lsquare.io/mcp

$ claude mcp add --transport http lsquaremcp https://mcp.lsquare.io/mcp

• MCP uses its own sign-in flow. LSQUARE_KEY is the SDK's API key; keep it in your server's environment.

Find each MCP server and how it runs: stdio, HTTP, a new server per request, or serverless. Keep its existing tools, transport, and MCP SDK version. LSquare supports mcp 1.x and 2.x, and fastmcp 3.x and 4.x.

Install lsquare in your project's Python environment with its package manager and update its dependency files. Python 3.10 or later is required. For pip, allow the beta release with --pre:

$ pip install --pre lsquare

• After installing, read the Python SDK README and its linked reference. If the README isn't packaged separately, read the installed package description with python -c "from importlib.metadata import metadata; print(metadata('lsquare').get_payload())".

Python SDK README

Create the client once at module level and share it across your servers. Read the key from the environment; never hardcode or commit it. Import this client wherever you instrument a server.

import os
from lsquare import LSquare

lsquare = LSquare(api_key=os.environ.get("LSQUARE_KEY"))

Request API key

Call instrument() before the server runs or starts serving requests. Use your existing server instance and the shared client. On mcp 2.x, add your own middleware first and keep the middleware list intact afterwards.

from lsquare.mcp import instrument

instrument(mcp, lsquare)

Follow the reference's recipe for your host. Pass the relevant options in the same instrument() call:

• New server per request: instrument inside the factory, sharing the client across requests.
• Vercel: import wait_until from vercel.functions, pass wait_until=wait_until, and serve statelessly using the setting for your MCP SDK version.
• AWS Lambda, or Cloud Run without always-on CPU: pass flush_before_reply=True so sending is awaited before replying.
• Lambda with Mangum: keep the client at module level, never shut it down per invocation, and follow the reference's session-manager recipe for your MCP SDK version.
• Long-running HTTP / ASGI server: call await lsquare.ashutdown() in the app's shutdown or lifespan hook after the server stops. Do not call SDK methods inside a Python signal handler.
• Cloudflare Python Workers are unsupported: the SDK needs threads and sockets and stays disabled there.

Host setup and shutdown recipes

The LSquare additions are marked below. This example uses mcp 1.x FastMCP; keep the imports and tool registrations your project already uses.

from mcp.server.fastmcp import FastMCP
import os                          # ADD THIS
from lsquare import LSquare        # ADD THIS
from lsquare.mcp import instrument # ADD THIS

lsquare = LSquare(api_key=os.environ.get("LSQUARE_KEY")) # ADD THIS

mcp = FastMCP("shop")
# Keep your existing tool registrations here.

instrument(mcp, lsquare) # ADD THIS

if __name__ == "__main__":
    mcp.run(transport="stdio")

Set LSQUARE_DRY_RUN=1 in the server's environment and start it with your project's usual command. Call one existing tool through your MCP client and confirm [lsquare dry-run] lines appear on stderr. Nothing is sent in dry run. Keep stdout free of logs on stdio servers, then run your project's tests and type checks.

• When ready to send events, remove LSQUARE_DRY_RUN, set LSQUARE_KEY in the server's environment, and restart it.

Run the command for your coding agent from your project directory. It adds the remote LSquare MCP as lsquaremcp. Use the existing connection if it already points to this URL.

$ codex mcp add lsquaremcp --url https://mcp.lsquare.io/mcp

$ claude mcp add --transport http lsquaremcp https://mcp.lsquare.io/mcp

• MCP uses its own sign-in flow. LSQUARE_KEY is the SDK's API key; keep it in your server's environment.