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>
This commit is contained in:
66
docs/operations/mcp-access.md
Normal file
66
docs/operations/mcp-access.md
Normal file
@@ -0,0 +1,66 @@
|
||||
# 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`.
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user