MCP For AI Tools

LIME includes a read-only MCP endpoint for external AI tools. It lets an AI client inspect scans, score summaries, issue groups, paginated occurrences, report availability, and relevant settings from an existing LIME instance.

MCP is read-only. AI tools can analyze LIME data, but they cannot create scans, retry scans, delete scans, change settings, or mark false positives.

Current status

MCP is available when it is enabled in Settings > Integrations and an MCP key has been generated.

Current behavior:

• LIME exposes POST /mcp on the Shopkeeper/API service.
• LIME returns JSON responses for MCP initialization, tool listing, and tool calls.
• GET /mcp streaming is not enabled.
• MCP session state, OAuth, scoped keys, and write tools are not implemented.
• Origin validation currently allows requests with no Origin header and localhost origins. Server-to-server clients and local bridges normally work because they omit Origin.

What you will need

1. A LIME instance that includes MCP support.
2. Access to Settings in the LIME dashboard.
3. MCP enabled under Settings > Integrations.
4. A generated MCP key.
5. An AI tool that supports remote Streamable HTTP MCP servers, or a local HTTP-to-stdio bridge.

Endpoint

Production endpoint:

https://<your-lime-host>/mcp

Local development endpoint:

http://localhost:8080/mcp

Use the Shopkeeper/API host, not the docs-site host. For example, do not point AI clients at https://sumanbasuli.github.io/lime/ or a static docs domain.

Generate a key

1. Open Settings.
2. Open Integrations.
3. Enable MCP server.
4. Select Generate MCP key.
5. Copy the key immediately. LIME only shows the raw key once.
6. Store the key in your AI tool or local environment.

Use environment variables when your AI tool supports them:

export LIME_MCP_URL="https://lime.example.com/mcp"
export LIME_MCP_KEY="lime_mcp_xxxxxxxxxxxxxxxxx"

Generic AI client config

Many AI tools use a JSON config with an mcpServers object. Use this shape when the tool supports remote HTTP MCP servers:

{
  "mcpServers": {
    "lime": {
      "type": "http",
      "url": "https://lime.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${LIME_MCP_KEY}"
      }
    }
  }
}

Some clients use transport: "streamable-http" instead of type: "http":

{
  "mcpServers": {
    "lime": {
      "transport": "streamable-http",
      "url": "https://lime.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${LIME_MCP_KEY}"
      }
    }
  }
}

Use the field names your AI tool documents. The required parts are the /mcp URL and the bearer authorization header.

Local bridge config

Use this pattern when an AI tool only supports local stdio MCP server entries:

{
  "mcpServers": {
    "lime": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "${LIME_MCP_URL}",
        "--header",
        "Authorization: Bearer ${LIME_MCP_KEY}"
      ],
      "env": {
        "LIME_MCP_URL": "https://lime.example.com/mcp",
        "LIME_MCP_KEY": "lime_mcp_xxxxxxxxxxxxxxxxx"
      }
    }
  }
}

The bridge package is an example pattern, not a LIME dependency. Use your organization's preferred bridge if it supports Streamable HTTP and custom request headers.

Smoke test

After enabling MCP and configuring the key, verify that missing credentials are rejected on a POST request:

curl -i -X POST "$LIME_MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "ping"
  }'

Then test an initialized request:

curl -i "$LIME_MCP_URL" \
  -H "Authorization: Bearer $LIME_MCP_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": {
        "name": "lime-smoke-test",
        "version": "0.1.0"
      }
    }
  }'

Expected result: HTTP 200 with a JSON MCP initialize response. A missing or invalid key should return HTTP 401.

TypeScript client example

Use this when you are testing an integration outside an AI client UI:

npm install @modelcontextprotocol/sdk

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const url = process.env.LIME_MCP_URL;
const key = process.env.LIME_MCP_KEY;

if (!url || !key) {
  throw new Error("Set LIME_MCP_URL and LIME_MCP_KEY.");
}

const transport = new StreamableHTTPClientTransport(new URL(url), {
  requestInit: {
    headers: {
      Authorization: `Bearer ${key}`,
    },
  },
});

const client = new Client({
  name: "lime-integration-check",
  version: "0.1.0",
});

await client.connect(transport);

const tools = await client.listTools();
console.log(JSON.stringify(tools, null, 2));

await client.close();

Run it:

LIME_MCP_URL="https://lime.example.com/mcp" \
LIME_MCP_KEY="lime_mcp_xxxxxxxxxxxxxxxxx" \
npx tsx lime-mcp-client.ts

Available read-only tools

The MCP endpoint exposes these tools:

• list_scans
• get_scan
• list_scan_issues
• get_issue_detail
• get_report_metadata
• get_settings

Use list_scan_issues first, then pass the returned kind and key into get_issue_detail when you need paginated occurrence details.

Example AI prompts

List the latest LIME scans and show me which ones are partial.

For scan 66386d89-8564-40bb-93b3-c4a6fe70fcd4, summarize the top failed accessibility issues by severity and occurrence count.

Show me the first 20 occurrences for the highest-impact issue, including affected URLs and selectors.