agents-store NocoDB Dev Setup Verification
nocodb-dev uses two NocoDB surfaces:
- MCP — discovery only (
getTablesList,getTableSchema,getBaseInfo). Authenticated byxc-mcp-token. - CLI / REST API — every schema write (table, field, view, hook). Authenticated by an API token.
Both must work before you can plan and apply schema changes safely.
Required Environment Variables
| Variable | Required | Surface | Description |
|---|---|---|---|
NOCODB_MCP_URL |
Yes (MCP) | MCP | Full MCP endpoint URL including the path-id, e.g. https://your-instance.com/mcp/ncc17zpg5n7v9vs8. From NocoDB → Integrations → MCP. |
NOCODB_MCP_TOKEN |
Yes (MCP) | MCP | xc-mcp-token minted in NocoDB → Integrations → MCP. |
NOCODB_URL |
Yes (CLI/API) | API/CLI | Base instance URL, e.g. https://your-instance.com. Used by nc and direct REST calls. |
NOCODB_API_TOKEN |
Yes (CLI/API) | API/CLI | API token from NocoDB → Account Settings → API Tokens. |
NOCODB_VERBOSE |
No | CLI | Set to 1 to print resolved IDs from the CLI. |
The two token pairs are distinct. Sharing one variable across both transports is the regression captured in LEARNINGS.md of the nocodb-ops plugin (2026-05-06).
Verification Steps
Run in order. Stop at the first failure and consult the troubleshooting table.
Step 1 — MCP discovery
Call mcp__nocodb__getTablesList with no parameters.
- Pass: returns a list of table names and IDs.
- Fail: see Troubleshooting → MCP rows.
Step 2 — MCP schema read
Pick any table ID from Step 1. Call mcp__nocodb__getTableSchema with tableId.
- Pass: returns columns + views.
- Fail: the token may lack base-level access.
Step 3 — CLI base list
nc base:list
- Pass: returns one or more base IDs (prefix
p). - Fail: see Troubleshooting → CLI rows.
Step 4 — CLI table list
Using a base ID from Step 3:
nc table:list <baseId>
- Pass: returns table IDs (prefix
m). - Fail: the API token may not be shared with that base.
Step 5 — Optional API ping
curl -sS -H "xc-token: $NOCODB_API_TOKEN" "$NOCODB_URL/api/v3/data/<baseId>/<tableId>/count" | jq
- Pass: returns
{ "count": <number> }. - Fail: likely auth or path issue — confirm token has
readscope on the base.
Troubleshooting
| Symptom | Surface | Likely cause | Fix |
|---|---|---|---|
| "Protected resource does not match" | MCP | NOCODB_MCP_URL is missing the /mcp/<path-id> suffix |
Use the full MCP endpoint URL from NocoDB → Integrations → MCP |
| 401 Unauthorized | MCP | NOCODB_MCP_TOKEN invalid/expired |
Regenerate the token in NocoDB → Integrations → MCP |
| 401 Unauthorized | CLI/API | NOCODB_API_TOKEN invalid/expired |
Regenerate in NocoDB → Account Settings → API Tokens |
| 403 Forbidden | Either | Token lacks permission for the base | Share the base with the token's user, or use a higher-privilege token |
nc: command not found |
CLI | CLI not installed | npx skills add nocodb/agent-skills |
"Tool not found" mcp__nocodb__* |
MCP | Server name mismatch | Confirm .mcp.json names the server nocodb (not nocodb-1) |
| Connection refused | Either | Server down or wrong host | curl -sSI $NOCODB_URL to confirm reachability |
Empty nc base:list |
CLI | Token has no shared bases | Have an admin share at least one base with the token's user |
What This Skill Does NOT Cover
- Provisioning a NocoDB instance (admin task).
- Generating tokens (done in NocoDB UI).
- Selecting which base / source to operate on (use the table-management skill).
- Schema modification itself (use table-management, field-management, view-management, webhooks).
After Verification
Once all steps pass:
- Read mcp-patterns to understand what the MCP can and cannot do.
- Read api-reference when you need the REST API surface.
- Read cli-reference for
nccommand syntax. - Use table-management, field-management, view-management, webhooks to make changes.