MCP in Claude Code: How to Connect Databases and APIs

Table of Contents

• Quick reference
• How MCP works
• Step 1: add a local server (stdio)
• Step 2: connect a remote server (HTTP)
• Step 3: choose the scope
• Step 4: share the configuration without sharing secrets
• Step 5: verify that it works
• 8 security rules before connecting anything serious
• And Superpowers, where does it fit?
• Plan for your team

Once installed, Claude Code reads files and runs commands in your terminal. For it to query your database, review your issues or call an API, you need MCP (Model Context Protocol), the open protocol Anthropic published to connect models with external tools.

This guide explains how to add MCP servers, how to share them with your team without committing credentials to Git, and which security rules to follow before you connect anything serious.

Quick reference

Server	Transport	Command	Suggested scope	Key caution
Local Git	stdio (uvx)	claude mcp add git -- uvx mcp-server-git	user	Check which write operations it exposes
PostgreSQL	stdio (npx)	claude mcp add db -- npx -y @bytebase/dbhub --dsn "$DATABASE_READONLY_URL"	project	Only with a read-only user
Remote API	http	claude mcp add --transport http mi-api https://mcp.ejemplo.com/mcp	project	The token goes in a variable, never in the file
File system	stdio (npx)	claude mcp add archivos -- npx -y @modelcontextprotocol/server-filesystem .	local	Limit the path to the project, never the root of the disk

How MCP works

Claude Code acts as the client. Each MCP server is a process or service that exposes tools, for example run_query or list_issues. During the session, Claude sees those tools, decides when to call them and asks for your permission depending on your configuration.

There are two ways to connect:

• stdio: Claude Code starts the server as a local process (usually with npx or uvx) and communicates through standard input and output. This is the usual approach for tools that run on your machine.
• http: the server lives at a remote URL. This is the usual approach for cloud services. Many large services publish official MCP servers with OAuth authentication.

Step 1: add a local server (stdio)

The general form is:

claude mcp add <nombre> -- <comando> [argumentos...]

The -- separator is mandatory: it separates the options of claude from the command that starts the server. Without it, Claude Code tries to interpret the server's arguments as its own.

Example with a Git server:

claude mcp add git -- uvx mcp-server-git

Example with PostgreSQL using DBHub, pointing to an environment variable with a read-only user:

export DATABASE_READONLY_URL="postgresql://lectura:****@db.tuempresa.com:5432/analytics"
claude mcp add db -- npx -y @bytebase/dbhub --dsn "$DATABASE_READONLY_URL"

Step 2: connect a remote server (HTTP)

claude mcp add --transport http mi-api https://mcp.ejemplo.com/mcp \
  --header "Authorization: Bearer $MI_API_TOKEN"

If the server uses OAuth, do not add the header: open a session, run /mcp and follow the authentication flow in the browser.

Step 3: choose the scope

Each server is saved in one of three scopes, which you choose with --scope:

• local (default): only for you and only in this project. Useful for tests or servers with personal credentials.
• project: written to .mcp.json at the root of the repo. The whole team receives it when they clone. Claude Code asks for approval the first time someone uses a project server.
• user: for you in all your projects. Ideal for general tools such as Git.

claude mcp add --scope project db -- npx -y @bytebase/dbhub --dsn '${DATABASE_READONLY_URL}'

Step 4: share the configuration without sharing secrets

The .mcp.json file accepts environment variables with the ${VARIABLE} syntax (and ${VARIABLE:-default_value}). This way the file can go into the repo without credentials:

{
  "mcpServers": {
    "mi-api": {
      "type": "http",
      "url": "https://mcp.ejemplo.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MI_API_TOKEN}"
      }
    },
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_READONLY_URL}"]
    }
  }
}

Each developer exports their own variables (export MI_API_TOKEN=...) or loads them from a secrets manager, and nobody has to touch the file.

Step 5: verify that it works

claude mcp list        # estado de todos los servidores
claude mcp get db      # detalle de uno
claude mcp remove db   # eliminarlo

Inside a session, /mcp shows which servers are connected and which tools they expose. If a server shows an error, the most common cause is an environment variable that is not defined in the shell where you opened Claude Code.

8 security rules before connecting anything serious

1. Least privilege. Read-only database users, tokens with only the permissions they need. Never give the agent an administrator user.
2. Zero secrets in the repo. Environment variables in .mcp.json, always.
3. Bounded paths. The file server should only see the project folder.
4. Official or reviewed servers. Prefer the ones published by the service's own provider. An MCP server runs code on your machine: check where it comes from before installing it.
5. Human approval for anything that writes. Use Claude Code's permissions so that tools which modify data ask for confirmation, or a PreToolUse hook with a matcher such as mcp__db__.* to block or log certain calls.
6. Reasonable timeouts. If a server takes a long time to start (the first download with npx is usually slow), raise the timeout with the MCP_TIMEOUT variable, in milliseconds.
7. Output limit. If a tool returns huge results, adjust MAX_MCP_OUTPUT_TOKENS and ask for queries with LIMIT so you do not fill the model's context.
8. Replicas before production. For analysis, connect a replica or a staging environment, not the main database.

And Superpowers, where does it fit?

MCP gives Claude Code access to tools. Superpowers gives it a method: a skills plugin that forces it to design before coding, write a step-by-step plan and work test-first. They are complementary: with MCP, Claude can query your database; with Superpowers, it does so inside a reviewed plan.

If you do not have it yet, the guide on how to install Superpowers in Claude Code explains how to install it from the marketplace in five minutes.

Plan for your team

1. Standardize the tool. Install Claude Code on the team and decide which servers are for general use (user scope) and which belong to the project.
2. Create credentials for the AI. Ask infrastructure for a dedicated database user, read-only and with access limited to the schemas needed.
3. Version .mcp.json. Commit it to the repo with environment variables and document in the README which variables each developer needs.
4. Measure the impact. If the team solves problems faster, that changes your cost structure. Run the numbers with the profit margin calculator.