# MCP Setup

> Install the Lev MCP server in your AI client, sign in through Auth0, and verify the connection with a read-only call before you build workflows.

Source: https://www.lev.com/docs/build/mcp/setup

Last updated: June 2026

---
Before you start

- A Lev account with access to the data you plan to query — MCP tools inherit your existing Lev permissions.
- An MCP-compatible client: Claude Code, Claude Desktop, Claude.ai, Cursor, VS Code, or another client that supports streamable HTTP and OAuth.
- A browser reachable from the machine running the client — the Auth0 sign-in flow opens in your default browser.

If you are building a backend sync job or a headless service, use the [REST API](/build/api-overview) with an [API key](/build/api-keys) instead of MCP. MCP is designed for interactive clients.

## Environments

Pick the right endpoint for where you are in the build.

**Lev MCP endpoints**

- **Hosted:** https://mcp.lev.com/mcp — production MCP server for connecting real clients. Use this unless you are debugging the server itself.
- **Local development:** http://localhost:8000/mcp — run the server locally from the lev-mcp-server repo for debugging tool behavior.

Register the Lev MCP server with your client so the tools show up in its catalog.

#### Claude

In Claude Desktop or [claude.ai](https://claude.ai), open **Settings → Connectors → Add custom connector**. Fill in the fields below, click **Add**, then sign in when the browser opens.

*Connector details*

```text
Name:             Lev
URL:              https://mcp.lev.com/mcp
OAuth Client ID:  FPVfGZHwa9wvqhLwmXiaZyJPEjnaVAZB
```

#### ChatGPT

In ChatGPT, open the app store and search for Lev, or go directly to [Lev in the ChatGPT app store](https://chatgpt.com/apps/lev/asdk_app_69f1045fd7f881918fbbf039156fc4b4).

#### Claude Code

Run the following command in your terminal to add the Lev MCP server to Claude Code. See the [Claude Code documentation](https://docs.claude.com/en/docs/claude-code/mcp) for details.

*Terminal*

```bash
claude mcp add --transport http --client-id FPVfGZHwa9wvqhLwmXiaZyJPEjnaVAZB --callback-port 9876 --scope user Lev https://mcp.lev.com/mcp
```

After adding the server to Claude, authenticate with Lev:

*Terminal*

```bash
claude /mcp
```

#### Cursor

Add the following to your `~/.cursor/mcp.json` file. See the [Cursor documentation](https://docs.cursor.com/context/model-context-protocol) for details.

*~/.cursor/mcp.json*

```json
{
  "mcpServers": {
    "Lev": {
      "url": "https://mcp.lev.com/mcp",
      "auth": {
        "CLIENT_ID": "FPVfGZHwa9wvqhLwmXiaZyJPEjnaVAZB",
        "scopes": [
          "openid",
          "email"
        ]
      }
    }
  }
}
```

#### VS Code

Open the Command Palette (`Cmd+Shift+P`) and run **MCP: Open User Configuration**. Replace the file contents with the JSON below and save. Click the **Start** codelens that appears above the `Lev` entry. When prompted for **OAuth Client ID**, paste `FPVfGZHwa9wvqhLwmXiaZyJPEjnaVAZB` and leave Client Secret blank.

*mcp.json*

```json
{
  "servers": {
    "Lev": {
      "type": "http",
      "url": "https://mcp.lev.com/mcp"
    }
  }
}
```

#### Other

For direct bearer-token access for custom agents and automation, contact [help@lev.com](mailto:help@lev.com).

Complete an OAuth sign-in so the client holds a JWT it can send with every tool call.

1. **Trigger the first tool call.** The client discovers the authorization server from `<mcp-server-url>/.well-known/oauth-authorization-server`.
2. **Sign in on the Auth0 page.** Your default browser opens to the Auth0 hosted sign-in — complete authentication there.
3. **Let the client exchange the code.** Auth0 redirects back with an authorization code; the client exchanges it for an RS256-signed JWT and stores it securely.
4. **Reuse the token automatically.** Subsequent tool calls reuse the JWT until it expires, then the client silently refreshes — you never set `Authorization` headers yourself.

For the token lifecycle, scopes, and account switching, see [MCP Authentication](/build/mcp/auth).

Run three bounded checks to prove the server is reachable, authenticated, and returning the right data before you trust it with real work.

1. **Confirm identity and account.** Ask the client *"Use the Lev MCP server to get my profile."* — it should call `get_my_profile` and return your email, user ID, and available accounts.
2. **Confirm a read tool works.** Ask *"List my first five deals in Lev."* — it should call `list_deals` with `limit=5` and return real data.
3. **Confirm the tool catalog looks right.** Ask the client to list the Lev MCP tools it has discovered — you should see the core groups for deals (including checklists), documents, vaults, contacts, companies, notes, lenders, placements, pipelines, term sheets, market data, billing, and account. Some MCP Apps hosts also surface app-only viewer helpers.

The server registers 60 tools across 13 groups, including app-only helpers for inline document and memo viewers. If a client hides app-only helpers, treat the group names and core business tools as the validation signal rather than the exact count.

## Troubleshoot

Match the symptom you see to the matching row before retrying the validate checks.

**Common MCP setup failures**

- **No tools discovered:** Check the URL and scheme, confirm the client can reach the host, and make sure the config file is valid JSON. Claude Desktop silently ignores malformed configs.
- **OAuth loop or immediate 401:** Clear cached tokens in the client and retry. If the browser window never opens, confirm the client is allowed to launch URLs and the machine has a default browser.
- **403 on a tool that used to work:** Your Lev role may have changed. MCP tools inherit live permissions — there is no cached authorization layer.
- **404 or 5xx with no detail:** Check the server /health endpoint. If lev_api is degraded, the backend is the cause, not the MCP server.
- **Wrong account in tool output:** Use the switch_account tool to pin the MCP session to a specific account slug. See MCP Authentication for details.
- **Responses feel truncated:** Lender search results can exceed tool-output token limits. Narrow the deal or ask for a specific slice. See MCP Errors & Limits for known payload gaps.

**Next:** [MCP Tools](/build/mcp/tools) — explore the tool surface now that the connection is live.

Sharing this with a non-technical teammate? Send them the [Lev MCP Quickstart](/build/mcp/quickstart) — a one-pager with the install box and a few real prompts to try.