Connect Lev through MCP

Last updated: March 2026

Use MCP when you want an AI client to discover Lev capabilities, authenticate safely, and call tools against live account-aware data. Treat setup as an integration surface, not just a config copy-paste.
When to Use MCPAuth ModelConfigure the ClientValidate the Connection

MCP Setup Summary

When to use
  • You want Cursor, Claude, or another MCP client to retrieve Lev data and execute account-aware tool actions.
  • You want a human-in-the-loop workflow instead of a purely server-side integration.
Required scopes
  • The connected user must already have access to the resources the client will read or mutate.
  • Use GET /me or auth validation to inspect the scopes actually granted to the session.
Headers
  • Authorization: Bearer <jwt_or_api_key>
  • X-Origin-App: <client-name>
Response schema
MCP discovery and tool outputs are client-specific, but the underlying Lev API responses continue to use the standard request_id/timestamp/data envelope.
Examples
JSON config, TypeScript bridge, curl verification

When to Use MCP

Use MCP when the user experience is conversational, iterative, or tool-driven:
  • Good MCP fit: broker copilots, analyst assistants, workflow copilots inside Cursor or Claude, and operator tools that need retrieval plus action.
  • Bad MCP fit: nightly ETL jobs, deterministic product syncs, and backend workflows that never need a human-facing agent.
If you are building a service-to-service integration, prefer the REST API plus Data Sync Patterns.

Choose Your Auth Model

Recommended auth choices

Interactive client
Use JWT / OAuth when the end user signs in from Cursor, Claude, or another MCP-compatible client.
Hosted bridge
Use API keys only when your own secure server-side bridge stores the credential and mediates access.
Verification
Always test account identity, visible scopes, and at least one safe read action before enabling larger workflows.

Configure the Client

The exact wire format depends on the client, but the durable pieces are the same:
  • Point the client at the Lev MCP endpoint.
  • Use a clear X-Origin-App value.
  • Prefer OAuth / JWT when the client supports an interactive sign-in flow.

Configuration examples

json
{
"mcpServers": {
  "lev": {
    "url": "https://api.levcapital.com/mcp",
    "headers": {
      "X-Origin-App": "cursor-lev-client"
    }
  }
}
}

Validate the Connection

Before you build workflows, validate the setup in this order:
  1. Confirm the client sees the Lev MCP server.
  2. Confirm auth succeeds without a manual token workaround.
  3. Confirm a read-only action returns account-aware data.
  4. Confirm the client can surface errors and request IDs clearly.
Start with one of these safe checks:
  • "Which Lev account is this connection using?"
  • "List my first five deals."
  • "What scopes are granted to this session?"

Troubleshoot Common Failures

401 vs 403
A 401 usually means the token is missing, invalid, or expired. A 403 means auth succeeded but the connected user does not have the necessary access for the requested resource.

Common MCP failures

No tools discovered
Check the MCP server URL, confirm the client can reach it, and verify the auth handshake completed.
Auth loop
Check whether the client expects OAuth / JWT while the connection is configured with a static API key or vice versa.
Read succeeds, writes fail
Inspect granted scopes and the connected user role before assuming the payload is wrong.
Context is noisy
Move broad discovery into recipes and agent workflows. Keep the MCP client focused on small, account-aware tool calls.

What's next

Once the client can connect and complete a safe read, move to workflow design.

Continue to Agent Workflows

Related Articles

Build on Lev's PlatformAuthenticationQuickstartAPI KeysPagination