Quickbase MCP Setup Guide

This guide explains how to wire the vendored Quickbase MCP server into Sasha so Claude can automate Quickbase apps. Follow it when provisioning new environments or rotating credentials.

Prerequisites

• A Quickbase realm (e.g., acme.quickbase.com) and an app ID that Sasha can manage.
• A Quickbase user token scoped to the app above. Grant table-level permissions for every table Claude should touch.
• Claude CLI installed and authenticated (claude --version works) because registrations run through claude mcp add.
• Sasha repo cloned with the vendored server at integrations/mcp/quickbase/ (tracked in git).

Generate a Quickbase user token

1. In Quickbase, open My Apps → User tokens.
2. Click New user token and name it something like Sasha MCP.
3. Select the target app ID and grant access to every table Sasha will automate.
4. Copy the token (looks like QB-xxxxxx). You only see it once—store it in your password manager.

Installation & Builds

The repo already includes the compiled server, but if you update dependencies run:

cd integrations/mcp/quickbase
npm install         # optional if you need to refresh node_modules
npm run build       # not required for the current JS-only entrypoint
node smoke-test.js  # requires valid Quickbase env vars

The project ships with a committed node_modules/ mirror so Docker builds don’t hit the network. Keep it in sync with package.json if you upgrade the SDK.

Configuration in Sasha

1. Navigate to Settings → Tools → Quickbase Workspace Automation.
2. Fill in:
   • Realm hostname (host only, e.g., acme.quickbase.com).
   • App ID (e.g., bq8xk2hj).
   • User token (paste once; it is encrypted at rest).
   • Optional defaults: table ID, report ID, timeout, retry count.
3. Click Save configuration.
4. Run Test connection – this invokes quickbase_test_connection via the MCP smoke harness.
5. Once the smoke test passes, click Register to run claude mcp add quickbase ....

The settings UI persists everything to /home/sasha/config/mcp/quickbase.json. The user token is encrypted via the shared secretStore helper.

Manual CLI registration

If you need to register from a terminal, use:

claude mcp add quickbase \
  --env QB_REALM=acme.quickbase.com \
  --env QB_APP_ID=bq8xk2hj \
  --env QB_USER_TOKEN=qbtoken_xxx \
  -- integrations/mcp/quickbase/run-quickbase-mcp.js

Use claude mcp remove quickbase to deregister.

Smoke Testing

integrations/mcp/quickbase/smoke-test.js launches the server over stdio and executes quickbase_test_connection. It requires the same env vars as runtime:

cd integrations/mcp/quickbase
QB_REALM=acme.quickbase.com \
QB_APP_ID=bq8xk2hj \
QB_USER_TOKEN=qbtoken_xxx \
node smoke-test.js

The script logs the available tools and captures a 500-character snippet so operators can confirm the API responded.

Troubleshooting

Symptom	Fix
Quickbase MCP run script not found	Ensure integrations/mcp/quickbase/run-quickbase-mcp.js exists and is executable (chmod +x).
Quickbase credentials are incomplete	Realm, app ID, and token must all be present. Save them in the UI before testing/registration.
Quickbase API error 401/403	Verify the user token is scoped to the correct app and tables; rotate the token if revoked.
Registration succeeds but CLI shows ✗	The wrapper may not inherit your Node env (nvm). Use absolute paths or the provided run script.
Smoke test hangs	Make sure Claude CLI is installed and not prompting for analytics; also confirm the Quickbase API isn’t behind a VPN.

File Locations

• Server entrypoint: integrations/mcp/quickbase/index.js
• Wrapper: integrations/mcp/quickbase/run-quickbase-mcp.js
• Smoke test: integrations/mcp/quickbase/smoke-test.js
• Config file: /home/sasha/config/mcp/quickbase.json
• UI card: claudecodeui/src/components/ToolsSettings.jsx (renderQuickbaseIntegration)
• Service layer: claudecodeui/server/services/quickbaseMcpService.js

Keep this guide alongside the AWS Cost/CloudWatch playbooks so operators can repeat the process quickly when rotating tokens or cloning environments.