MCP Gateway Governance for Teams: Permissions, Audit Logs, Quotas, and Claude Code Setup

After a team brings Claude Code into daily engineering workflows, MCP integration usually moves quickly from “the demo works” to harder governance questions:

• Who can call which tool?
• Which project spent the tokens?
• Who approved a risky tool call?
• Where do we look when something goes wrong?

This guide focuses on the MCP Gateway as the middle layer for team governance. It covers three core areas: permission tiers, audit logs, and usage quotas. It also includes a standard Claude Code + ClaudeAPI configuration pattern for teams that want a maintainable control layer.

What is an MCP Gateway?

MCP, or Model Context Protocol, is an open protocol Anthropic introduced in November 2024 to standardize how AI applications connect to external tools and data sources.

For a solo developer, connecting Claude Code directly to an MCP server can be enough. In a team, direct connections create problems:

• Permission boundaries blur. An intern and an architect may reach the same database MCP server.
• Costs become opaque. Token usage is hard to attribute by member, project, or workflow.
• Audit records are scattered. Tool-call history lives across local clients and individual logs.

An MCP Gateway sits between Claude Code, or another MCP client, and the MCP servers. It becomes the enforcement point for authentication, authorization, logging, and rate limits.

Claude Code client
       |
       v
  MCP Gateway          <- governance layer: permissions / audit / quotas
       |
  -----+-----
  |    |    |
  v    v    v
MCP  MCP  MCP
Server A B C

Claude Code client
       |
       v
  MCP Gateway          <- governance layer: permissions / audit / quotas
       |
  -----+-----
  |    |    |
  v    v    v
MCP  MCP  MCP
Server A B C

Governance layer 1: team permission tiers

Start with least privilege. Each identity should only access the tools required for its role and project.

A simple three-tier structure is usually enough to start:

In the ClaudeAPI console, you can create separate API keys for team members. At the Gateway layer, route requests from different keys or identities to different MCP server subsets.

Example Gateway routing policy:

# mcp-gateway-config.yaml
# Illustrative example, not a complete config for a specific gateway project.
routes:
  - match:
      api_key_prefix: "dev-"
    allow_servers:
      - github-mcp
      - docs-search-mcp
      - ci-runner-mcp
    deny_servers:
      - production-db-mcp

  - match:
      api_key_prefix: "intern-"
    allow_servers:
      - docs-search-mcp
    deny_servers:
      - "*"

# mcp-gateway-config.yaml
# Illustrative example, not a complete config for a specific gateway project.
routes:
  - match:
      api_key_prefix: "dev-"
    allow_servers:
      - github-mcp
      - docs-search-mcp
      - ci-runner-mcp
    deny_servers:
      - production-db-mcp

  - match:
      api_key_prefix: "intern-"
    allow_servers:
      - docs-search-mcp
    deny_servers:
      - "*"

The Gateway must be able to inspect authentication metadata before forwarding the request to the MCP server. Implementations vary: some teams use reverse proxies, Envoy filters, service mesh policies, or dedicated MCP gateway products. Treat the YAML above as a policy shape, not a drop-in implementation.

Governance layer 2: audit logs

Audit logs should be searchable, complete enough to investigate incidents, and consistent across tools.

A useful MCP tool-call audit record includes:

{
  "event_type": "mcp_tool_call",
  "timestamp": "2026-07-02T09:12:34Z",
  "api_key_id": "key_dev_xxxx",
  "member_id": "engineer_alice",
  "project_id": "proj_backend_v2",
  "mcp_server": "github-mcp",
  "tool_name": "create_pull_request",
  "input_summary": "repo: acme/api, branch: feat/xxx",
  "tokens_used": 1240,
  "model": "claude-sonnet-4-6",
  "latency_ms": 890,
  "status": "success"
}

{
  "event_type": "mcp_tool_call",
  "timestamp": "2026-07-02T09:12:34Z",
  "api_key_id": "key_dev_xxxx",
  "member_id": "engineer_alice",
  "project_id": "proj_backend_v2",
  "mcp_server": "github-mcp",
  "tool_name": "create_pull_request",
  "input_summary": "repo: acme/api, branch: feat/xxx",
  "tokens_used": 1240,
  "model": "claude-sonnet-4-6",
  "latency_ms": 890,
  "status": "success"
}

Key practices:

• Redact inputs. Tool arguments can contain secrets, user data, source code, or database identifiers. Store summaries by default, not full payloads.
• Separate audit storage from application logs. Audit records should not disappear when app logs rotate.
• Define retention rules. Many enterprise teams start at 90 days or more, but regulated industries may require longer retention.
• Alert on risky tools. Calls such as delete_*, exec_*, drop_*, or production database writes should trigger real-time review or notification.
• Detect anomalies. A single key calling a tool 100 times in five minutes is usually worth investigating.

Audit logs should answer three questions quickly:

1. Who called the tool?
2. What did the tool try to do?
3. Which model, project, and token budget were involved?

Governance layer 3: usage quotas

Token limits should exist at three levels:

member quota < project quota < team quota

member quota < project quota < team quota

Examples:

• Member quota: each member can use up to 500,000 tokens per day.
• Project quota: a monthly reporting project can use up to 2 million tokens.
• Team quota: the entire team gets alerts at 80% of monthly budget.

Without Message Batches API support in the ClaudeAPI path, teams should control cost through routing, prompt caching, streaming, queues, and gateway-level limits.

Recommended cost controls:

1. Model routing:
   • claude-haiku-4-5-20251001 for formatting, summaries, and simple classification
   • claude-sonnet-5 or claude-sonnet-4-6 for most daily engineering tasks
   • claude-opus-4-7 for complex reasoning and high-value decisions
2. Prompt caching for repeated system prompts and tool definitions.
3. Streaming for better user experience and fewer timeout-driven retries.
4. Queue-based execution for low-priority batch tasks.

Claude Code + MCP Gateway configuration

Prerequisites

Before configuring Claude Code, make sure you have:

• a ClaudeAPI API key from the ClaudeAPI console
• an MCP Gateway instance listening on a local or internal network endpoint
• Claude Code with custom MCP server support
• a Gateway member token separate from the ClaudeAPI key

As of the source article date, Claude Code documentation describes MCP configuration through commands such as claude mcp add, project-level .mcp.json, and user-level configuration. Always check your installed Claude Code version and current docs.

Step 1: configure ClaudeAPI as the model backend

For Claude Code or Anthropic SDK-style usage, use:

export ANTHROPIC_BASE_URL="https://gw.claudeapi.com"
export ANTHROPIC_API_KEY="your-claudeapi-key"

export ANTHROPIC_BASE_URL="https://gw.claudeapi.com"
export ANTHROPIC_API_KEY="your-claudeapi-key"

In Python:

import anthropic

client = anthropic.Anthropic(
    api_key="your-claudeapi-key",
    base_url="https://gw.claudeapi.com",
)

import anthropic

client = anthropic.Anthropic(
    api_key="your-claudeapi-key",
    base_url="https://gw.claudeapi.com",
)

Do not use the MCP Gateway token as your ClaudeAPI key. They are separate authentication systems.

Step 2: register the MCP Gateway in Claude Code

Use claude mcp add to add the Gateway as an MCP server. For team-shared config, project scope is usually preferable because it can live in the repository while secrets stay in environment variables.

claude mcp add --transport http gateway --scope project \
  "http://localhost:8080/mcp" \
  --header "Authorization: Bearer ${MCP_GATEWAY_TOKEN}"

claude mcp add --transport http gateway --scope project \
  "http://localhost:8080/mcp" \
  --header "Authorization: Bearer ${MCP_GATEWAY_TOKEN}"

The project .mcp.json can use a structure like:

{
  "mcpServers": {
    "gateway": {
      "type": "http",
      "url": "${MCP_GATEWAY_URL:-http://localhost:8080}/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_GATEWAY_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": {
    "gateway": {
      "type": "http",
      "url": "${MCP_GATEWAY_URL:-http://localhost:8080}/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_GATEWAY_TOKEN}"
      }
    }
  }
}

Important:

• MCP_GATEWAY_TOKEN authenticates the member to the Gateway.
• The ClaudeAPI key authenticates model access.
• Do not commit either secret to the repository.

Step 3: verify the tool-call path

The easiest end-to-end test is to ask Claude Code to list or call a harmless tool through the Gateway.

If you want to test from code, use a minimal tool-call-style request to verify the model path separately:

import anthropic

client = anthropic.Anthropic(
    api_key="your-claudeapi-key",
    base_url="https://gw.claudeapi.com",
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=256,
    tools=[
        {
            "name": "list_available_tools",
            "description": "List MCP tools available to the current identity.",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "List the tools I can currently use."
        }
    ],
)

print(response.content)

import anthropic

client = anthropic.Anthropic(
    api_key="your-claudeapi-key",
    base_url="https://gw.claudeapi.com",
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=256,
    tools=[
        {
            "name": "list_available_tools",
            "description": "List MCP tools available to the current identity.",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "List the tools I can currently use."
        }
    ],
)

print(response.content)

This code verifies the model/tool-call shape. The actual MCP Gateway route should be validated from Claude Code or your MCP client, because the Gateway sits in the MCP transport path.

Common errors

Pre-launch checklist

Before shipping a team MCP governance setup, verify:

• [ ] Each member has an independent key or identity.
• [ ] Key naming includes role or project prefixes.
• [ ] Gateway routing covers every MCP server.
• [ ] There is no accidental allow-all default rule.
• [ ] Audit logs are written to independent storage.
• [ ] Input redaction has been tested.
• [ ] Member, project, and team quotas are configured.
• [ ] 80% budget alerts are tested.
• [ ] High-risk tools such as delete_* and exec_* trigger real-time alerts.
• [ ] Claude Code uses https://gw.claudeapi.com as the model backend.
• [ ] A test denial path returns the expected error code and audit record.

FAQ

How is an MCP Gateway different from permission checks in application code?

Application-level checks depend on each client behaving correctly. If someone bypasses the client and calls an MCP server directly, those checks may not run.

A Gateway acts as a network enforcement point. All traffic must pass through it, so authorization can be applied consistently before requests reach MCP servers.

Should audit logs store full tool-call payloads?

Usually no. Tool inputs may contain secrets, private data, or source code. Store summaries by default. If full payload retention is required, encrypt it separately and restrict access.

Is the Claude Code MCP config path fixed?

No. Claude Code supports different scopes, such as local, project, and user. Project scope is often best for team governance because .mcp.json can define shared structure while secrets come from environment variables.

What happens when a quota is exceeded?

The Gateway should return a clear error, commonly a 429 Too Many Requests style response. The client should stop or retry according to policy. Teams should alert at 80% of the quota to avoid hard failures.

Should the MCP Gateway run locally or in the cloud?

Small teams can start locally. Larger teams usually benefit from an internal network or private cloud deployment so policies, audit logs, and quotas are centralized.

Where do I specify ClaudeAPI model IDs?

Model IDs still go in the normal Messages API model field. Examples include:

claude-opus-4-7
claude-sonnet-5
claude-sonnet-4-6
claude-haiku-4-5-20251001

claude-opus-4-7
claude-sonnet-5
claude-sonnet-4-6
claude-haiku-4-5-20251001

MCP tool calls use the same model-selection pattern as ordinary Claude API calls.

Next steps

1. Create member API keys in the ClaudeAPI console.
2. Define role prefixes or identity mapping for your team.
3. Deploy an MCP Gateway instance.
4. Add permission rules for each MCP server.
5. Implement structured, redacted audit logs.
6. Add member, project, and team quotas.
7. Test the denial path before production rollout.
8. Configure Claude Code with the Gateway endpoint and run an end-to-end test.

For related implementation topics, see:

• Claude API error guide
• Claude API Tool Use guide
• Claude API pricing guide

Sources

• Anthropic: Introducing the Model Context Protocol
• MCP transport specification
• MCP authorization specification
• Claude Code MCP documentation
• ClaudeAPI

ClaudeAPI is an independent third-party technical service provider. It is not affiliated with Anthropic and does not guarantee the availability of Anthropic services.