Files
gcp_solution_architecture_a…/docs/operations/mcp-access.md
Jonathan Boniface ed104e5697 feat: add local tools and read-only remote MCP servers
Increment 6 of .scratch/solution-architect-agent/spec.md, test-first.

- app/tools/mcp.py: MCP client and catalog exposing only allowlisted,
  readOnlyHint tools as framework-neutral ToolSpecs; unreachable servers
  and failed calls become discovery gaps; ADC auth with quota project.
- app/tools/local.py: Mermaid structure check and Terraform fmt,
  validate and plan in a scratch copy; apply is never constructed.
- Tool factory gives roles their named local tools and bundle MCP
  servers; pillar advisors get general-tier documentation tools.
- providers/gcp.yaml: 42 allowlisted tools reviewed against live
  tools/list of 12 Google Cloud MCP servers (snapshot in
  providers/reviews/), excluding data-reading and secret-capable tools.
- scripts/list-mcp-tools.py, docs/operations/mcp-access.md (IAM deny
  policy, service account roles), cloud-discovery and iac-validation
  Skills, MCP and Terraform settings, pytest asyncio auto mode.
- 31 new tests; full suite 189 passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-16 10:14:05 +01:00

3.6 KiB

Remote MCP access: Google Cloud

How to give the solution architect agent safe, read-only access to Google Cloud's hosted MCP servers. The servers the agent uses, and the only tools it may call on each, are listed in providers/gcp.yaml.

How the agent limits itself

  • Allowlist. An agent is only ever offered tools named in a server's allow list. Every other tool on the server is invisible to it.
  • Read-only check at startup. If any allowlisted tool doesn't declare readOnlyHint: true, the agent refuses to start.
  • Content excluded. Tools that return data content are excluded even though they are read-only: Cloud SQL execute_sql_readonly, Cloud Storage read_object/read_text/list_objects, and generic Kubernetes reads that can return Secrets (get_k8s_resource, describe_k8s_resource).
  • Permission per Execution. Tools that read your environment (cloud_read) run only after the user grants permission in that Execution. Pre-approved Executions deny it unless the caller passes allow_cloud_read=true.

These are defence in depth. Enforce read-only access in Google Cloud as well.

Set up a project the agent may read

  1. Enable the APIs of the products you want discovered. A product's MCP endpoint is available once its API is enabled, for example compute.googleapis.com, container.googleapis.com, run.googleapis.com, sqladmin.googleapis.com, pubsub.googleapis.com, cloudasset.googleapis.com, monitoring.googleapis.com and networkmanagement.googleapis.com. A disabled API shows up as a recorded discovery gap, not a failure.

  2. Create a dedicated service account for the agent, and grant it only:

    • roles/mcp.toolUser, to call MCP tools
    • roles/viewer, or narrower viewer roles for the products in scope
    • roles/cloudasset.viewer, for asset inventory and IAM analysis
  3. Deny read-write tool calls for every principal with an IAM deny policy. Save the policy as policy.json:

    {
      "rules": [
        {
          "denyRule": {
            "deniedPrincipals": ["principalSet://goog/public:all"],
            "deniedPermissions": ["mcp.googleapis.com/tools.call"],
            "denialCondition": {
              "title": "Deny read-write tools",
              "expression": "api.getAttribute('mcp.googleapis.com/tool.isReadOnly', false) == false"
            }
          }
        }
      ]
    }
    

    Then attach it to the project:

    gcloud iam policies create mcp-deny-policy \
      --attachment-point=cloudresourcemanager.googleapis.com/projects/PROJECT_ID \
      --kind=denypolicies \
      --policy-file=policy.json
    
  4. Give the agent credentials. It authenticates with Application Default Credentials: the attached service account on Cloud Run or GKE, or GOOGLE_APPLICATION_CREDENTIALS locally. Set MCP_QUOTA_PROJECT when quota should be charged to a project other than the credentials' project.

For local development, gcloud auth application-default login supplies ADC for your user.

Reviewing the allowlists

Upstream tool sets change. To review them:

  1. Refresh the snapshot. tools/list works without credentials, and the script lists tools without calling any:

    .venv/bin/python scripts/list-mcp-tools.py gcp --json --no-auth > providers/reviews/gcp-mcp-tools.json
    
  2. Read the diff. For each new read-only tool, decide whether it returns inventory or configuration metadata (allow it) or data content or secrets (leave it out).

  3. Update the allow lists in providers/gcp.yaml. tests/test_providers.py fails if an allowlisted tool is missing from the snapshot or isn't read-only.

Last reviewed 2026-09-16, against all 12 servers.