For developers

API & MCP Documentation

Complete Reference for Developers

Contents

MCP Â· AI assistants

Connect your AI assistant to ScreenLeads

The MCP server lets Claude, or any compatible client, query your ScreenLeads data in natural language, with your credentialâ€™s permissions.

Connection details

MCP endpoint

https://mcp.pre.screenleads.com/mcp

HTTP transport (JSON-RPC).

Health check

https://mcp.pre.screenleads.com/health

Should return ok: true and backendAuthMode: passthrough.

Backend environment

https://api.pre.screenleads.com

The MCP forwards your credential to the API in passthrough mode.

Security mode

passthrough

The MCP stores no global credentials: your assistant only sees what your API key can see.

Up and running in 4 steps

1
Check the health endpoint
Open it in a browser and confirm it returns ok: true.
2
Configure your MCP client
Register the server with the /mcp URL and the Authorization (Bearer with your API key) and X-ScreenLeads-Client-Id headers. Some clients manage headers in their UI instead of JSON.
3
List the tools
Confirm you see tools for companies, branding, devices, ads, promotions, plans, tokens, invoices, media and webhooks.
4
Run a real query
For instance screenleads_health_check, or ask in natural language what permissions your API key has.

Configuration & examples

MCP client configuration (JSON)

{
  "mcpServers": {
    "screenleads": {
      "url": "https://mcp.pre.screenleads.com/mcp",
      "headers": {
        "Authorization": "Bearer <SCREENLEADS_API_KEY>",
        "X-ScreenLeads-Client-Id": "<SCREENLEADS_CLIENT_ID>"
      }
    }
  }
}

cURL Â· Authenticated call

curl -X POST https://mcp.pre.screenleads.com/mcp \
  -H 'Authorization: Bearer <SCREENLEADS_API_KEY>' \
  -H 'X-ScreenLeads-Client-Id: <SCREENLEADS_CLIENT_ID>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "screenleads_health_check", "arguments": {} }
  }'

What your assistant can query

Companies & branding

Visible companies, logos and brand tokens.

Devices & ads

Screens, assigned ads and playback diagnostics.

Promotions

Active promotions, QR codes, activation and deactivation.

Plans & tokens

Visible plans, token packs, balance and transactions.

Billing

Your companyâ€™s visible invoices and recent charges.

Webhooks & permissions

Configured integrations and your API key scopes.

Try these questions

What permissions does my API key have â€” can it write ads?
List the companies my user can see.
Check which ads are assigned to device 1 and whether promotions are linked.
Compute the current token balance and list the latest transactions.
Prepare the change for ad 15, but donâ€™t execute it until I confirm.

Security & scope

Passthrough mode: your credential is forwarded to the API; the MCP stores no global admin credentials.
Your assistant can only query what your API key can query on the backend.
Writes are a two-step flow: the MCP returns a preview and only executes after your explicit confirmation.
Tokens, passwords and secrets are redacted in MCP responses.

REST API

Integrate the ScreenLeads API

Companies, devices, ads, promotions, plans, tokens and invoices â€” always scoped to your credentialâ€™s permissions.

Connection details

Backend environment (PRE)

https://api.pre.screenleads.com

Pre-production environment to validate your integration before going live.

Authentication

X-API-KEY + X-ScreenLeads-Client-Id

A ScreenLeads API key scoped to your client or company. Also accepted as Authorization: Bearer.

How to get your credential

1
Create or select an API client
In ScreenLeads, the API client represents your integration.
2
Create an API key with scopes
Read or write scopes and, if applicable, a companyScope to restrict it to one company.
3
Store rawKey and client_id
The only two values your integration needs; no recurring login. The key can be revoked or rotated from the backend.
4
Call the API with both headers
Send the API key and the client_id on every request.

Examples

cURL Â· Request with API key

curl https://api.pre.screenleads.com/companies \
  -H 'X-API-KEY: <SCREENLEADS_API_KEY>' \
  -H 'X-ScreenLeads-Client-Id: <SCREENLEADS_CLIENT_ID>'

cURL Â· JWT login (internal testing only)

curl -X POST https://api.pre.screenleads.com/auth/login \
  -H 'Content-Type: application/json' \
  --data '{"username":"usuario@screenleads.com","password":"PASSWORD"}'

Security

Use an API key scoped to your client or company: it can be revoked or rotated with no downtime.
Never paste API keys, tokens or passwords into chats, shared documents or screenshots.
The login JWT works, but it expires and depends on a user session: keep it for internal testing.

{ "mcpServers": { "screenleads": { "url": "https://mcp.pre.screenleads.com/mcp", "headers": { "Authorization": "Bearer <SCREENLEADS_API_KEY>", "X-ScreenLeads-Client-Id": "<SCREENLEADS_CLIENT_ID>" } } } }

curl -X POST https://mcp.pre.screenleads.com/mcp \ -H 'Authorization: Bearer <SCREENLEADS_API_KEY>' \ -H 'X-ScreenLeads-Client-Id: <SCREENLEADS_CLIENT_ID>' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ --data '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "screenleads_health_check", "arguments": {} } }'