smart_toy Model Context Protocol

MCP Integration

Integrate Lygo with your AI agents via Model Context Protocol. Manage shortlinks, domains, and imports directly from Claude, GPT, or any compatible MCP client. 30 tools available.

psychology

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows LLMs (Claude, GPT, etc.) to connect to external services in a secure and structured way. Instead of writing code each time, the AI directly calls tools exposed by the MCP server.

chat

Write in natural language

"Create a link for this URL with urlCode 'promo'"

arrow_forward

MCP executes the call

The server translates to POST /api/links

check_circle

Structured result

The AI receives the created link and responds

settings

Configuration

The Lygo MCP server is configured via environment variables. Only LYGO_AGENT_API_KEY is required.

Variable Required Default Description
LYGO_AGENT_API_KEY YES — Service account API key (format slk_xxx). Create from Platform Admin → Service Accounts.
LYGO_API_BASE NO https://app.lygo.it Lygo API base URL.
LYGO_DEFAULT_TENANT_ID NO — Default tenant used when tools do not receive an explicit tenantId.
LYGO_REQUEST_TIMEOUT_MS NO 20000 HTTP timeout in milliseconds for each API call.
tips_and_updates

How to obtain the API key

Go to app.lygo.it → Settings → Service Accounts → New service account. Assign the necessary scopes and copy the generated key: it cannot be viewed again.

install_desktop

Claude Desktop Setup

Add the following configuration to the claude_desktop_config.json file:

computer macOS: ~/Library/Application Support/Claude/
window Windows: %APPDATA%\Claude\ 
{
  "mcpServers": {
    "lygo": {
      "command": "npm",
      "args": ["--prefix", "/path/to/shortlink_platform/mcp/server", "run", "start"],
      "env": {
        "LYGO_AGENT_API_KEY": "slk_xxx",
        "LYGO_DEFAULT_TENANT_ID": "tnt_xxx"
      }
    }
  }
}

Replace /path/to/shortlink_platform/mcp/server with the absolute path to the mcp/server folder of the project. Restart Claude Desktop after making the change.

key

Authentication headers sent by the MCP server

x-api-key: {LYGO_AGENT_API_KEY}
x-request-id: mcp-{UUID}
Content-Type: application/json
build

Available Tools 30 tools

monitor_heart

Utility

lygo_health

Checks that the MCP server and Lygo API are reachable. No parameters.

domain

Workspace

lygo_list_tenants

Lists all tenants (workspaces) accessible with the current key. No parameters.

link

Links 5 tools

lygo_list_links

Lists a tenant's links with pagination and sort-by-clicks support.

Params: tenantId? (optional, uses default if not specified)

lygo_create_link

Creates a new shortlink.

Params: originalUrl (required), tenantId?, redirectType? ("301"|"302"), urlCode?, domainId?

lygo_get_link

Retrieves details and statistics for a specific link by urlCode.

Params: tenantId (required), urlCode (required)

lygo_update_link

Updates the destination or redirect type of an existing link.

Params: tenantId (required), urlCode (required), originalUrl (required), redirectType?

lygo_delete_link

Permanently deletes a link from the tenant.

Params: tenantId (required), urlCode (required)

public

Domains 5 tools

lygo_list_domains

Lists all custom domains configured for the tenant.

Params: tenantId?

lygo_create_domain

Adds a new custom domain to the tenant.

Params: tenantId (required), domain (required)

lygo_refresh_domain

Refreshes the DNS verification status of a domain.

Params: tenantId (required), domainId (required)

lygo_set_default_domain

Sets the default domain for the tenant's shortlink generation.

Params: tenantId (required), domainId (required)

lygo_delete_domain

Removes a custom domain from the tenant.

Params: tenantId (required), domainId (required)

upload_file

CSV Import 9 tools

lygo_create_csv_import_job

Creates a new CSV import job. Returns jobId and a presigned S3 uploadUrl.

Params: tenantId?, fileName? (default "import.csv"), domainId?

lygo_upload_csv_text

Uploads CSV content as text via PUT to the presigned S3 URL.

Params: uploadUrl (required), csvText (required)

lygo_upload_csv_file

Uploads a CSV file from the local filesystem via PUT to the presigned S3 URL.

Params: uploadUrl (required), filePath (required)

lygo_validate_import_job

Starts CSV row validation without importing. Reports invalid URLs and duplicate codes.

Params: jobId (required)

lygo_start_import_job

Starts the actual import execution. The job is processed asynchronously.

Params: jobId (required)

lygo_list_import_jobs

Lists all import jobs for the tenant with their current status, with pagination.

Params: tenantId?, limit?, cursor?

lygo_get_import_job

Retrieves the status and details of a specific import job. Use for polling until completion.

Params: jobId (required)

lygo_get_import_job_results

Retrieves row-by-row results of a completed job, including errors and created links.

Params: jobId (required), limit?, cursor?

lygo_pause_import_job

Pauses a running import job.

Params: jobId (required)

lygo_resume_import_job

Resumes a paused import job.

Params: jobId (required)

lygo_cancel_import_job

Permanently cancels an import job.

Params: jobId (required)

notifications

Notifications 3 tools

lygo_list_notifications

Lists the tenant's in-app notifications.

Params: tenantId?, limit?

lygo_mark_notification_read

Marks a single notification as read.

Params: notificationId (required)

lygo_mark_all_notifications_read

Marks all tenant notifications as read.

Params: tenantId?

manage_accounts

Service Accounts / Platform 4 tools

warning

These tools require the platform:manage scope and operate at the platform level, not per tenant.

lygo_platform_list_service_accounts

Lists all platform service accounts. No parameters.

lygo_platform_create_service_account

Creates a new service account with scopes and a reference user.

Params: name (required), actAsUserId (required), scopes (required, string[]), expiresAt?

lygo_platform_rotate_service_account_key

Rotates the API key of a service account, invalidating the previous one.

Params: serviceAccountId (required)

lygo_platform_revoke_service_account

Revokes and disables a service account.

Params: serviceAccountId (required)

account_tree

CSV Import Flow

1

Create the job

Call lygo_create_csv_import_job with the tenantId. You receive the jobId and the presigned S3 uploadUrl.

2

Upload the CSV

Use lygo_upload_csv_text (or lygo_upload_csv_file for a file on disk) passing the uploadUrl and the CSV content. See the "CSV Format" section for the expected structure.

3

Validate (optional)

Call lygo_validate_import_job. The system analyzes each row and reports errors (invalid URLs, duplicate urlCodes, etc.) without creating links.

4

Start the import

Call lygo_start_import_job with the jobId. The job is processed asynchronously.

5

Monitor status

Use lygo_get_import_job to poll the job status (running → completed). You can use lygo_pause_import_job and lygo_resume_import_job to control it, or lygo_cancel_import_job to cancel it.

6

Retrieve results

When the job is completed, use lygo_get_import_job_results to see created links and any row-by-row errors.

shield

Scopes

Each API key can be restricted to specific scopes. Configure permissions in the Service Accounts panel when creating the key.

Allowed Operations Required Scope
Read links links:read
Create / update / delete links links:write
Read import jobs imports:read
Create and manage CSV imports imports:manage
Read custom domains domains:read
Manage custom domains domains:manage
Read analytics analytics:read
Read in-app notifications notifications:read
Manage service accounts (platform) platform:manage
table_chart

CSV Format

The CSV file must have a header row with at least the original_url column. Other columns are optional.

Column Required Description
original_url YES Full destination URL.
url_code NO Custom code. If omitted, auto-generated (8 characters).
redirect_type NO 301 or 302. Default: 302. 
original_url,url_code,redirect_type
https://example.com/page,my-code,301
https://another.com,,302

Start integrating with your AI agents

Create an account, generate an API key, and connect Lygo to your favorite LLM in minutes.

Create free account api See also API Reference