Lucid MCP vs Lucid API for AI Agents

TL;DR

• Lucid MCP and the Lucid REST API have overlapping but not identical coverage. The MCP server is strong on the document loop: search, read, generate diagrams, edit blocks, share. The REST API owns the account-governance surface: folders, ownership transfer, SCIM provisioning, and Enterprise Shield audit logs. For Lucid specifically, the MCP server exposes more granular in-canvas editing than the public REST API historically has.
• MCP auth is OAuth only, with Dynamic Client Registration (DCR) and Client ID Metadata Documents (CIMD), and a browser consent flow per user. The REST API adds API keys and admin-authorized account tokens, which are the only paths that run without a browser session. Your credential model changes depending on which you choose.
• The MCP server has hard limits worth knowing before you design around it: search returns up to 200 documents, generated mind maps and org charts cap at 1000 nodes, and a single share call accepts up to 100 email addresses.
• For multi-tenant B2B agents, neither path eliminates per-user credential isolation. You still need a token vault, rotation, and revocation solved at the infrastructure layer, regardless of which path you build against.
• Scalekit's Lucid connector wraps the Lucid MCP server with per-user token storage, scoped tools, and audit logging, so the MCP vs API decision does not change your auth infrastructure.

Your agent needs to read and build Lucid documents: find the architecture diagram, summarize it, draw a new flowchart, share it with a teammate. Lucid ships both a hosted MCP server at mcp.lucid.app/mcp and a REST API at api.lucid.co. They are not the same object: different capability coverage, different auth paths, different operational surface area in production. The choice is not permanent either, and for Lucid it has a twist most teams do not expect. Here's how to pick.

What Lucid MCP and Lucid API actually are

Lucid MCP

• The Lucid MCP server is Lucid's official, Lucid-hosted remote MCP endpoint, launched in November 2025 and available at ^{https://mcp.lucid.app/mcp}.
• It uses the Streamable HTTP transport and connects an agent to a user's Lucidchart and Lucidspark content: search, fetch and summarize, generate diagrams, edit document blocks, export pages, and share.
• Authorization runs on OAuth with DCR and CIMD, so a user authenticates through their existing Lucid account and no API key is involved.
• A Lucid account admin must enable MCP access before end users can connect, and the server is unavailable on FedRAMP accounts.

Lucid API

• The Lucid REST API exposes the broader platform: document create, search, read, copy, and trash; folders; collaborators; ownership transfer; document image export; embedding; SCIM user and group provisioning; and the Enterprise Shield document-management, legal-hold, and audit-log endpoints.
• Authentication accepts OAuth 2.0 user tokens (Authorization Code), admin-authorized account tokens, and API keys for most endpoints.
• Access tokens expire in one hour; refresh requires the ^{offline_access} scope.

What your agent can actually do with Lucid MCP vs API

The MCP server covers the conversational document loop well. The REST API owns folders, provisioning, and account governance. The most consequential difference for Lucid is the reverse of the usual pattern: the MCP server exposes direct block-level edit tools, while granular in-canvas modification on the REST side has historically required Lucid's Extension API with an active editor session.

The gap that bites

The MCP server cannot reach folders, ownership transfer, SCIM provisioning, or Enterprise Shield audit logs, and it cannot read documents stored in the Process or Cloud accelerators. If your agent governs an account rather than authoring inside one, that surface lives only in the REST API.

Neither path offers document-change webhooks, so any "react when a diagram changes" workflow needs polling on either side. These are architectural boundaries, not features shipping next month.

The auth path each one puts you on

The MCP server requires OAuth. There is no alternative: every user who connects completes a browser-based consent flow, DCR registers the client automatically, and the resulting token is scoped to that user's Lucid permissions. The server inherits exactly what the user can already see and do.

The REST API accepts three credential types. User tokens use the Authorization Code flow and a browser redirect, acting as the authorizing user. Account tokens are authorized once by an admin through the authorizeAccount endpoint, then decoupled from that user, which is what enables headless admin automation. API keys are tied to an individual user and cover most REST endpoints, though document sharing and embedding still require an OAuth client.

The headless constraint

This is the line that decides background work. The MCP server is built for interactive, user-present sessions; its OAuth-only model has no static credential, so a nightly sync or scheduled export with no user in the loop cannot complete the flow. The REST API's API keys and admin-authorized account tokens are the headless paths. If your agent runs on a schedule, that difference is the whole decision.

What you own in production

On the MCP path, Lucid manages hosting, the tool schemas, and permission enforcement. You still own per-user token storage, refresh against the one-hour access-token lifetime, revocation when a user disconnects, and tenant isolation. You also depend on an admin enabling MCP access for the account before anyone connects.

On the REST path, you own the full stack: endpoint selection, request construction, pagination, retry on 429 with the Retry-After header, and the token lifecycle. The maintenance trajectory differs too. MCP tool schemas can change when Lucid updates the hosted server, and Lucid does not publish a versioned contract for them. The REST endpoints are a more stable dependency for deterministic pipelines, at the cost of more code to maintain.

When to use MCP, when to use the API

Use Lucid MCP when:

• Your agent is interactive and user-present: a Claude, Cursor, or Copilot assistant where a person completes the OAuth consent and asks the agent to find, summarize, draw, or share Lucid documents in natural language.
• The core job is the document loop: search, read, generate diagrams, edit blocks, and share, without writing REST adapter code.
• You want in-canvas block-level editing, which the MCP server exposes directly through its add, edit, and delete tools.
• You are validating a Lucid agent concept quickly and want Lucid to maintain the tool surface.

Use the Lucid REST API when:

• Your agent runs headless: scheduled exports, background syncs, or batch document creation with no user present, where API keys or account tokens are the only viable credential.
• Your use case touches account governance: SCIM provisioning, ownership transfer, folder structure, or Enterprise Shield audit logs and legal hold.
• You need deterministic endpoint behavior you version and migrate on your own schedule.
• You are operating across an account on behalf of an admin rather than authoring as a single user.

The credential problem that exists on both paths

Both paths hand you a token, not a vault

Whether you choose the MCP path or the REST path, every user in a multi-tenant agent has their own Lucid credential. The MCP OAuth flow gives you a token per user. The REST API gives you a user token, account token, or API key per identity. In neither case does the path store that credential encrypted at rest, isolate it per tenant, refresh it before the one-hour expiry, or revoke it when a user disconnects.

The N-credential reality

Fifty customers means fifty credential lifecycles. A Lucid token can be revoked by the user or an admin at any time, and your agent has no built-in way to detect that until a call returns 401. For a background agent on a schedule, the failure is silent: requests start failing without an error anyone sees. This is infrastructure you build or buy, and the token type differs while the requirement stays identical.

Where Scalekit fits

Scalekit's Lucid connector handles the OAuth flow, per-user token storage, and rotation on the MCP path, so the MCP vs API decision does not change your auth infrastructure. Credentials never touch the agent runtime or the LLM context: the agent calls a tool, Scalekit resolves the right user's token server-side, and a result comes back.

Scoped tools, not a flat catalog

Before execution, the agent loads only the tools the current user's connected account is authorized to call, not the full Lucid surface. list_scoped_tools returns that scoped set; execute_tool runs a named tool for that user.

Scoping the surface to the handful of tools a task needs reduces token overhead and improves selection accuracy.

The fix is not better prompting. It is surface reduction. Scalekit's Lucid connector exposes named tools including lucidmcp_search, lucidmcp_fetch, lucidmcp_lucid_create_mind_map, lucidmcp_lucid_edit_item, lucidmcp_lucid_export_document_as_png, and lucidmcp_share_document_with_collaborators.

The agent loop, scoped to Lucid

The flow is discovery, then scope, then execution. The connection_name you pass must match the connection name configured in your Scalekit dashboard exactly; it is the single most common integration error. This example uses the Python SDK with the Anthropic framework.

One Virtual MCP endpoint, per-user identity

If you would rather hand any MCP-compatible client a single endpoint, Scalekit's Virtual MCP Server gives every agent role a scoped, user-specific MCP URL with no server to deploy, host, or maintain.

You declare a config once with create_config, listing which connections and tools are exposed, then call ensure_instance per user to mint a pre-authenticated URL. The endpoint is static; the identity is per-user. A Scalekit Virtual MCP URL looks like https://companyName.scalekit.com/mcp/v3/servers/<server-id>.

Observability for multi-tool, multi-tenant agents

When the same agent acts for many users across Lucid and other connectors, attribution is the hard part. Scalekit's auth logs record every tool call tied to the user who authorized it: who triggered it, which document was touched, and what came back.

For a multi-tenant agent, that audit trail is what lets you answer the security questionnaire about scope and revocation, rather than reconstructing it from application logs after an incident.

When Lucid does not expose the tool you need

The Lucid MCP server, and therefore the Scalekit connector, does not cover account-governance operations like SCIM or audit logs. If you need a Lucid action that is not in the tool list, you can wrap a REST endpoint with Scalekit's bring-your-own-connector flow, or request the tool from the Scalekit team. Ask in the Scalekit Slack community or on the Talk to us page.

Which one to build against

• If your agent is interactive and its job is the document loop, finding, summarizing, drawing, editing, and sharing Lucid content with a user present, the hosted MCP server is the faster path, and it is the one with direct block-level editing.
• If your agent runs headless or governs an account, batch jobs, scheduled exports, SCIM provisioning, or audit logging, use the REST API with API keys or account tokens, because the MCP server's OAuth-only model has no static credential.

Most production deployments end up using both: the assistant on MCP, the background and governance jobs on REST. Either way, the credential management problem is the same, and that is what needs production-grade infrastructure.

Browse the Scalekit Lucid connector.