Files
gcp_solution_architecture_a…/docs/operations/mcp-access.md
Jonathan Boniface a8ed21b89d
Some checks failed
validation / verify (push) Failing after 11s
docs: bring the README, runbook, glossary and ADR notes up to date
The README now covers the router, Change requests, overlay Skills, Jev's
uses and the current layout. VALIDATION.md no longer points at the removed
root Terraform. ADR-0004 and ADR-0007 gain dated "As built" notes; ADR-0007's
says which uses of Jev send Deliverable content.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-09 21:33:38 +01:00

69 lines
3.9 KiB
Markdown

# 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`](../../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`.
- **Replies are checked.** When Jev is configured, a server's reply that reads as instructions to the agent, as opposed to information, is withheld from the Specialist and logged (`JEV_GUARDRAIL`). Without Jev, replies pass through.
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`:
```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:
```bash
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:
```bash
.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.