Quickstart: Claude Code

Connect Claude Code to your VendOrca workspace and ask questions about your program in plain language. You need a workspace on the Team or Business plan.

Connect Claude Code#

1. Turn on agent access (Program Admin, once)#

   A Program Admin does this once for the whole workspace. If your workspace already shows On, skip to the next step.

   1. Open Agent access from the nav rail in the app.
   2. Read the disclosure. It explains what agent access exposes.
   3. Select I have read the above and I am turning agent access on for this workspace.
   4. Select Turn on agent access.

   Under This workspace, the badge now reads On.

2. Issue a token for yourself#

   Any user can do this, for themselves only. A Worker or Billing Entity sign-in shows a notice here until it's linked to its record. Ask your Program Admin to arrange that.

   1. Open Agent access.
   2. In Name this token, enter something you will recognize later, such as Claude Code on my laptop.
   3. Under What may it read?, select the scopes you need. For this quickstart, select Program, Workforce and Financial. Leave Personal data off unless you need names and email addresses.
   4. Keep Expires after (days) at the default of 90, or pick a shorter period.
   5. Select I have read the above and I am issuing this token in my own name.
   6. Select Issue token.

   Copy the value under Your new token right away. It looks like vo_agt.XXXXXXXX.XXXXXXXXXXXXXXXX… and is shown only once.

3. Add VendOrca to Claude Code#

   Run this in your terminal. Replace <server-name> with a name you choose, such as vendorca, and <token> with the token you copied.

   bashCopy

   claude mcp add --transport http <server-name> https://app.vendorca.com/api/v1/mcp --header "Authorization: Bearer <token>"

   To keep the token out of your shell history, read it into an environment variable first. The first command waits without showing anything: paste the token and press Enter.

   bashCopy

   read -rs VENDORCA_TOKEN && export VENDORCA_TOKEN
   claude mcp add --transport http vendorca https://app.vendorca.com/api/v1/mcp --header "Authorization: Bearer $VENDORCA_TOKEN"

   Claude Code saves the header in its MCP configuration. Treat that file like a password.

   Claude Code now lists the VendOrca tools your token can call. The list depends on your scopes and your role, so a token without Financial does not show the invoice or expense tools.

4. Ask a question#

   Start Claude Code and try prompts like these. Claude picks the tools; the table shows which ones it is likely to call.

   Prompt	Tools	Scopes needed
   "List my workers"	list_workers	read:workforce
   "Show the five most recent invoices"	list_invoices with order=desc	read:financial
   "What did we invoice by supplier last quarter?"	list_catalog to find the invoiced-total metric and the invoice supplier dimension, then run_semantic_query with a relative period of last quarter	read:program read:financial

   For the invoicing question, Claude reads your workspace's report catalog first, because the metrics you can query depend on your program configuration. Money comes back in integer cents, and "last quarter" means the previous calendar quarter in UTC. Report tools are available to staff roles only.

   If a supplier's name shows up as an object with "trust": "untrusted-third-party", that is expected. VendOrca labels text people typed so the agent treats it as data. See provenance envelopes.

5. Revoke the token when you are done#

   Open Agent access, find the token under Your tokens and select its Revoke <token name> button. The token stops working on its next request. You can then remove the server from Claude Code too.

If something fails#

• A 401 unauthorized response means the token is missing, mistyped, expired or revoked. Issue a new token and add the server again with it.
• If Claude lists no VendOrca tools, agent access may be off for the workspace, or your plan may not include it. Ask a Program Admin to check Agent access.

More fixes are in Troubleshooting.

Next steps#

• Tokens and scopes: choose the smallest set of scopes for each agent.
• Other MCP clients: connect Claude Desktop or another client.
• Reports API: the catalog and semantic query in detail.