BigBase MCP — From Zero to Deployed Site in 15 Minutes

[danielvm-git]

BigBase MCP — From Zero to Deployed Site in 15 Minutes

Mission: You're a solo developer. You want your AI coding agent to understand your
BigBase project, manage sites, trigger deploys, and query services — all through MCP.
By the end of this walkthrough, you'll have a working MCP connection and deploy your
first site.

---

Glossary

Term	Definition
MCP	Model Context Protocol — a standard way for AI agents to call external tools via JSON-RPC over HTTP
bb_ key	A BigBase organization API key (bb_ prefix). Used as a Bearer token for authenticated MCP tool calls
bb_dep_ key	A site-scoped deploy key (bb_dep_ prefix). Scoped to one site, used in CI/CD
Scope	A permission string attached to an API key. mcp:provision grants write access to MCP tools
Streamable HTTP	MCP transport. POST to /mcp with JSON-RPC. Server returns Mcp-Session-Id for session persistence
Tool tier	BigBase MCP classifies tools as Public (no auth), Read (any bb_ key), or Write (bb_ key + mcp:provision scope)

---

Step 1 — Create your BigBase account

curl -s -X POST https://bigbase.click/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}' | jq .

Expected response:

{
  "token": "eyJhbGci...",
  "refresh_token": "...",
  "user": { "id": 1, "email": "you@example.com" }
}

Save the token — this is your JWT session token. You'll need it for the next steps.

Verify: Run the login command below to confirm your account works.

curl -s -X POST https://bigbase.click/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}' | jq .token

You should see a new JWT token.

---

Step 2 — Create an organization

Every API key belongs to an organization. Create one:

# Replace YOUR_JWT with the token from Step 1
curl -s -X POST https://bigbase.click/api/orgs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT" \
  -d '{"name":"my-org","slug":"my-org"}' | jq .

Expected response:

{
  "data": { "id": 1, "name": "my-org", "slug": "my-org" }
}

Note the id — you'll need it to create API keys.

---

Step 3 — Create an MCP API key

This is the key your AI agent will use to talk to BigBase. The mcp:provision scope
grants access to write tools (create repos, sites, trigger deploys).

# Replace ORG_ID with the id from Step 2
curl -s -X POST https://bigbase.click/api/orgs/ORG_ID/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT" \
  -d '{"name":"mcp-key","scopes":["mcp:provision"]}' | jq .

Expected response:

{
  "data": {
    "id": 1,
    "name": "mcp-key",
    "scopes": ["mcp:provision"],
    "key": "bb_a1b2c3d4e5f6..."
  }
}

⚠️ The key is shown ONCE. Copy it now. You won't see it again.

This bb_ key is what your AI agent uses as a Bearer token. Treat it like a password.

---

Step 4 — Store the key securely with direnv

We use direnv so your API key is available to your agent
automatically — no hardcoding, no leaking into git.

4a. Install direnv

# macOS
brew install direnv

# Ubuntu / Debian
sudo apt install direnv

# Arch
pacman -S direnv

Then add the hook to your shell:

# Add to ~/.bashrc or ~/.zshrc
eval "$(direnv hook bash)"   # or direnv hook zsh

Open a new terminal (or source ~/.bashrc).

4b. Create .envrc in your project root

# In your project directory
echo 'export BIGBASE_API_KEY="bb_a1b2c3d4e5f6..."' > .envrc

Replace bb_a1b2c3d4e5f6... with the key from Step 3.

4c. Allow it

direnv allow

Verify: Run echo $BIGBASE_API_KEY — it should print your bb_ key.
Navigate away and back — the variable disappears and reappears. That's direnv working.

4d. Add .envrc to .gitignore

echo '.envrc' >> .gitignore
echo '.env' >> .gitignore

Never commit .envrc to git. It contains secrets.

---

Step 5 — Configure MCP for your agent

BigBase MCP is live at https://mcp.bigbase.click/mcp. Pick your agent below.

Claude Code

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "bigbase": {
      "type": "http",
      "url": "https://mcp.bigbase.click/mcp",
      "headers": {
        "Authorization": "Bearer ${BIGBASE_API_KEY}"
      }
    }
  }
}

Cursor / VS Code

Create .cursor/mcp.json (or .vscode/mcp.json):

{
  "servers": {
    "bigbase": {
      "serverUrl": "https://mcp.bigbase.click/mcp",
      "headers": {
        "Authorization": "Bearer ${BIGBASE_API_KEY}"
      }
    }
  }
}

⚠️ Cursor and VS Code use servers, not mcpServers. This is the most common copy-paste error.

OpenCode / MiMo Code

Create opencode.jsonc (OpenCode) or .mimocode/mimocode.json (MiMo Code) in your project root:

{
  "mcp": {
    "bigbase": {
      "type": "remote",
      "url": "https://mcp.bigbase.click/mcp",
      "headers": {
        "Authorization": "Bearer ${BIGBASE_API_KEY}"
      }
    }
  }
}

Pi Agent

Create .pi/mcp.json in your project root:

{
  "mcpServers": {
    "bigbase": {
      "url": "https://mcp.bigbase.click/mcp",
      "headers": {
        "Authorization": "Bearer ${BIGBASE_API_KEY}"
      }
    }
  }
}

Antigravity (Gemini CLI / IDE)

Edit ~/.gemini/settings.json (global) or .gemini/settings.json (project):

{
  "mcpServers": {
    "bigbase": {
      "serverUrl": "https://mcp.bigbase.click/mcp",
      "headers": {
        "Authorization": "Bearer ${BIGBASE_API_KEY}"
      }
    }
  }
}

Tip: Claude Code supports ${VAR} natively. For other agents, replace
${BIGBASE_API_KEY} with the literal bb_ value if interpolation doesn't work.
You can also set it as an actual environment variable in your shell profile.

---

Step 6 — Verify the connection

Ask your AI agent:

"Use the BigBase MCP to ping the server and list all available services."

Your agent should:

1. Call ping → get pong
2. Call list_services → get the full service catalog (auth, db, storage, deploy, etc.)

If you get "authorization required": Your agent isn't sending the Bearer token.
Check that your .envrc is loaded (echo $BIGBASE_API_KEY) and that the MCP config
references the env var correctly.

If you get "method tools/call is invalid during session initialization": Your agent
needs to call initialize first. This is normal — most MCP clients handle this
automatically. Restart your agent session.

---

Step 7 — Deploy your first site (the payoff)

Now that MCP is connected, ask your agent:

"Create a new BigBase site for my project and deploy it."

Your agent will use these MCP tools in order:

Step	Tool	What it does
1	create_repo	Registers your git repo with BigBase
2	create_site	Provisions a site (returns site_id + URL)
3	deploy_site	Triggers the deployment

Or, if you already have a repo on GitHub, skip to:

"Deploy the main branch of my GitHub repo to BigBase."

Your agent will call list_repos → find your repo → deploy_site.

---

Tool Reference

Public (no auth needed)

Tool	Description
ping	Health check
list_services	Catalog of all BigBase services
get_service_docs	API docs for a specific service
get_code_example	Framework-specific code snippets
list_frameworks	Supported frameworks (Node, Python, Go, SvelteKit...)
get_ci_template	GitHub Actions workflow YAML
deploy_guide	Step-by-step deploy walkthrough

Read (any bb_ key)

Tool	Description
list_repos	Git repos registered with your org
list_sites	Your provisioned sites
get_site	Site metadata (URL, branch, status)
get_deploy_status	Deployment status by ID
get_deploy_logs	Build logs for debugging

Write (bb_ key + mcp:provision scope)

Tool	Description
create_repo	Register a git repo
create_site	Provision a new site
deploy_site	Trigger a deployment
provision_ci_credentials	Generate CI/CD deploy token
revoke_site_key	Revoke a deploy key

---

Troubleshooting

Symptom	Fix
authorization required	Check $BIGBASE_API_KEY is set and MCP config references it
insufficient scope	Your API key needs mcp:provision scope — recreate with the right scopes
400 Bad Request: GET requires Mcp-Session-Id	Normal for raw GET. MCP uses POST. Your agent handles this automatically
email already registered	You already have an account — use /api/auth/login instead
MCP tools not showing up	Restart your agent session after adding the MCP config

---

Security Checklist

• .envrc is in .gitignore — never commit secrets
• API key has minimum required scopes (don't give mcp:provision if you only need read)
• Rotate keys periodically via DELETE /api/orgs/{id}/api-keys/{keyID} + create new one
• Site deploy keys (bb_dep_) are scoped to one site — use them in CI/CD, not as general API keys

---

Next Steps

• Read the full API reference: bigbase.click/docs
• Deploy a real project: Use get_code_example with your framework (Next.js, SvelteKit, Astro, Express...)
• Set up CI/CD: Use provision_ci_credentials to get a deploy token, add it as a GitHub secret
• Explore services: Ask your agent to call get_service_docs for auth, storage, or functions

---

Found this helpful? Have questions? Ask below — we're building this for solo devs like you.