Manual / Integrations / Claude / MCP

MCP — Connect your AI workspace to vestl

vestl exposes an MCP connector so supported AI clients — including Claude, Claude Desktop, and ChatGPT — can read your vestl data using natural language. “What’s our current inventory of Neutral Grain Spirit?” “Which lots need attention?” “Which products does this client own?”

The connector uses the same login you use for the web app, sees the same data, and obeys the same role-based permissions. There is no separate vestl AI account, and Claude cannot do anything you could not do yourself in vestl.

Status: v1, read-only. The first release reads companies, products, brands, tanks and lines, reference details, and current inventory. Actions that change records — drafts, publishing, scheduling, and inventory posting — remain in the vestl web app.

The inventory app

When you ask to show, review, browse, or inspect inventory, a compatible chat client opens a compact vestl inventory app directly in the conversation. It includes:

stocked-product, active-lot, attention, expiry, and on-hand-value summaries
searchable traceable lots with product, lot, location, status, quantity, and value
focused views for available stock, lots needing attention, and lots expiring within two weeks
a direct Open in vestl action when you need the full inventory workflow

The embedded app is read-only. It follows the chat client’s light or dark theme and safe-area settings, and it does not load scripts, fonts, or data from third-party origins. If a client does not support MCP Apps, vestl returns the same summary and first matching lots as normal text instead.

What MCP gives you

Ask questions in your data’s language. Instead of clicking through the products page, filtering, and exporting, ask: “List all active raw materials sourced from Cascade.” Claude reads the matching product records and answers.
Cross-reference without the tab dance. “Which brands does Maybel’s own?” — Claude checks the client, walks to its brands, and reports.
Use vestl as context for other work. Drafting an email to a vendor about a delayed shipment? Claude can read the relevant purchase order and vendor contact in the same conversation it’s writing the email.

What MCP does not do: replace the operator UI for routine work, run unattended, or grant the AI permissions you don’t have. Every tool call runs as you, with your role, against your organization’s data.

How auth works

Claude connector requests carry your vestl access token. The connector uses the same permission checks as the web app:

You sign in at app.vestl.io.
You generate (or copy) a bearer token from your Account → Connectors page.
You paste the token into your MCP client (Claude Desktop config, Custom Connector form, etc.).
Each Claude action carries that token. vestl resolves it back to your user record, role, and organization, then applies the same permissions you have in the web app.

Each token belongs to the organization that was active when you generated it. If you work in more than one organization, generate a separate token while each organization is active. Changing organizations in the web app does not retarget an existing token.

If a token is lost or copied somewhere you no longer trust, revoke it from Account → Connectors. Signing out of the web app does not revoke a personal access token. Removing your membership from the token’s organization invalidates that token automatically.

Roles still apply

Every MCP tool applies the same read permission as its matching vestl page. Company, brand, and Tanks & Lines tools are available to admins, production managers, compliance officers, and read-only users. Product reads also include finance users. Inventory reads remain available to every authenticated role, matching the inventory API. A role that cannot open the equivalent data through vestl receives a permission denial when the AI invokes the tool.

A read-only user cannot use Claude to make changes. Claude sees the permission denial and stops. You do not need to think about which tools your role allows; vestl enforces it at every tool call.

Connect Claude Desktop

Claude Desktop reads MCP server config from a JSON file. On macOS that’s ~/Library/Application Support/Claude/claude_desktop_config.json. Open the file (or create it) and add a vestl entry under mcpServers:

{
  "mcpServers": {
    "vestl": {
      "url": "https://api.vestl.io/mcp",
      "headers": {
        "Authorization": "Bearer <your-vestl-token>"
      }
    }
  }
}

Replace <your-vestl-token> with the token from Account → Connectors. Save the file and quit/relaunch Claude Desktop. You should see vestl appear in the tools menu within a few seconds.

Staging vs production. Use https://api.staging.vestl.io/mcp while we soak v1 in staging. We’ll announce in-app when production opens up.

Connect Claude Code

Claude Code (the CLI) reads MCP servers from a project- or user-level config. The simplest path is to add vestl as a user-level server so it’s available in every project:

claude mcp add vestl --url https://api.vestl.io/mcp \
  --header "Authorization: Bearer <your-vestl-token>"

After running that command, claude mcp list should show vestl and claude itself will start auto-discovering vestl tools in subsequent sessions.

Connect via Custom Connector (claude.ai)

If you primarily use Claude in the browser at claude.ai, vestl can be added as a Custom Connector under Settings → Connectors → Add custom connector:

Connector name: vestl
URL: https://api.vestl.io/mcp
Authentication: Bearer token, paste the token from Account → Connectors.

Save, then enable the connector in any new conversation that needs it. Note: the claude.ai Custom Connector UI does not currently support OAuth flows for vestl, only static bearer tokens. We’ll move to OAuth as a v2 enhancement once the static-token soak is clean.

What you can ask v1 to do

The v1 connector is read-only. Claude can read:

Area	What Claude can read
Companies	Clients, vendors, internal companies, contacts, addresses, and brands
Products	Finished goods and raw materials, including each product’s base-unit symbol and physical dimension
Brands	Active brands with their parent client
Tanks & Lines	Tanks, vessels, and packaging lines, with capacity value, unit, and physical dimension
Inventory	On-hand lots, locations, status, expiry attention, quantities, and book value

Claude also reads enough context to answer in the right voice:

who you are, your role, and your organization
the vestl vocabulary glossary, so Claude uses the words your team uses

Things you cannot do in v1: create or edit drafts, publish formulas, fork BOMs, schedule manufacturing orders, post inventory adjustments, send purchase orders, run MRP. Those tools are landing in subsequent releases.

Example prompts to try

Once vestl is connected, here are prompts that exercise v1:

“List all active clients and how many brands each one has.”
“What raw materials do we source from Cascade? Include their SKUs.”
“Show me every finished good belonging to Maybel’s Spirits Co.”
“Which work centers are tanks and which are bottling lines?”
“Open inventory and show me what needs attention.”
“Show lots of Neutral Grain Spirit and tell me where they are stored.”
“Which lots expire in the next two weeks?”
“What’s my role in vestl?”
“Explain how versioning works for a Formula.”

For tasks not covered by v1’s read surface, Claude will say so honestly: “I can read this data, but the tool to publish a formula isn’t available yet — please publish it from the Formulas page in the web app.”

What’s coming next

Drafts — creating draft formulas and draft manufacturing orders with light confirmation.
State transitions — publishing formulas, forking formulas, scheduling manufacturing orders, and posting inventory adjustments with explicit confirmation.
Planning & MRP — reading planning dashboards, MRP previews, and schedule readiness.
Batches & genealogy — reading batch detail and lot genealogy.

We will update this page when each batch ships, and announce in the changelog inside the web app.

Security & data handling

Your token = your access. Treat the bearer token like a password. Don’t paste it into screenshares, public Slack, or git.
Multi-tenant. Every tool call is scoped to the organization bound to your token. Parent-client and unit lookups are scoped through the same organization boundary, so joined details cannot come from another organization.
Compliance still flows through the web app. TTB filings, audit log writes, and other compliance-sensitive changes are excluded from the v1 connector. They need the audit trail and signature flow the web app provides.
Rate limits. The connector is rate-limited (600 calls per 15-minute window per token). Normal interactive use is well below that ceiling.

If something feels wrong — a tool that returns data you shouldn’t see, a mutation that bypassed a role check — stop and email security@vestl.ai with the conversation transcript.