Verify MCP Servers Yourself

Run the MCP connectivity checker on your own machine to verify which AI tool integrations are working, which are read-only, and which need credentials. Layer 1 requires no sign-in. Layer 2 is opt-in and uses your own READONLY credentials.

Prerequisites

• Docker (for Layer 1 on bare metal) or native tools (in Codespace: bash, jq, python3 >=3.11, uv, node on PATH)
• Go Task (task command available)
• No cloud credentials needed for Layer 1

Layer 1: What Works (No Credentials)

Run the health check from your repo directory. It reports which servers are available and which need a sign-in.

adlc-framework (framework developers)

cd /path/to/adlc-framework
task -x mcp:doctor

b2b-metering (bc or vc tenants)

cd /path/to/b2b-metering
task -x mcp:doctor TENANT=bc
# or
task -x mcp:doctor TENANT=vc

os-ui (os startup)

cd /path/to/os-ui
task -x mcp:doctor

Layer 2: Live Server Check (Opt-In with Your READONLY Sign-Ins)

Once Layer 1 passes, you can verify that servers actually connect using your own read-only credentials. This layer refuses write-capable profiles.

Before Layer 2: Sign In to Your Clouds

For AWS servers:

aws sso login --profile <your-READONLY-profile>

For Azure servers: The b2b-metering task uses a separate Azure login folder per tenant (~/.azure-<tenant>), so sign in with:

AZURE_CONFIG_DIR=~/.azure-<tenant> az login --tenant <your-tenant-id>

For Claude Code (all layers): The claude CLI must be on your PATH.

Run Layer 2

For b2b-metering:

cd /path/to/b2b-metering
task -x mcp:verify TENANT=bc
# or
task -x mcp:verify TENANT=vc

For os-ui:

cd /path/to/os-ui
task -x mcp:verify

Expected Output: Layer 1 PASS

PASS check:prereq-runtime - docker reachable
CONFIG .mcp.bc.json servers=16 sha256=84a946c73bca
PASS check:config-declared - 16 server(s) across 1 file(s)
PASS check:config-drift - matches SSOT
PASS check:upgrade-check - no yanked pins
WARN server:awslabs-iac - linux/amd64 only; install fails on this host (see _platform note)
PASS check:readonly-safety - every declared server satisfies its _readonly rule
PASS check:test-l1 - every credential-free uvx/npx server launches --help
PASS server:markitdown - tools/list ok
PASS server:vizro-analytics - tools/list ok
PASS server:context7 - tools/list ok
PASS server:playwright-automation - tools/list ok
NEEDS-SIGNIN server:aws-mcp - AWS_PROFILE,AWS_REGION
NEEDS-SIGNIN server:awslabs-billing-cost-management - AWS_BILLING_PROFILE
NEEDS-SIGNIN server:awslabs-ecs - AWS_OPERATIONS_PROFILE,AWS_REGION
NEEDS-SIGNIN server:awslabs-iac - AWS_OPERATIONS_PROFILE,AWS_REGION
NEEDS-SIGNIN server:awslabs-network - AWS_OPERATIONS_PROFILE,AWS_REGION
NEEDS-SIGNIN server:azure - AZURE_SUBSCRIPTION_ID,AZURE_TENANT_ID
NEEDS-SIGNIN server:github - GITHUB_PERSONAL_ACCESS_TOKEN
NEEDS-SIGNIN server:grafana - GRAFANA_API_KEY,GRAFANA_URL
NEEDS-SIGNIN server:microsoft-fabric - AZURE_SUBSCRIPTION_ID,AZURE_TENANT_ID
NEEDS-SIGNIN server:microsoft-fabric-rti - AZURE_TENANT_ID
NEEDS-SIGNIN server:notion - http sign-in
NEEDS-SIGNIN server:terraform - TFE_TOKEN
SUMMARY layer=1 checks: PASS=6 FAIL=0 SKIP=0 WARN=1 servers: PASS=4 FAIL=0 SKIP=0 NEEDS-SIGNIN=12 total=16 verdict=VERIFIED
EVIDENCE /Volumes/Working/projects/b2b-metering/tmp/b2b-metering/test-results/mcp-doctor-l1-bc-20260911T205627Z.json

Variable fields (will differ on your machine): sha256= value, EVIDENCE timestamp and path, servers=<n> count. The PASS and NEEDS-SIGNIN lists depend on your declared config file.

Expected Output: Layer 1 FAIL (Docker Unreachable)

When Docker is not running and you have not set MCP_DOCTOR_RUNTIME=native:

FAIL check:prereq-runtime - docker unreachable (MCP_DOCTOR_RUNTIME=docker) - start Docker or set MCP_DOCTOR_RUNTIME=native
SUMMARY layer=1 checks: PASS=0 FAIL=1 SKIP=0 WARN=0 servers: PASS=0 FAIL=0 SKIP=0 NEEDS-SIGNIN=0 total=0 verdict=FAILED

Fix: Start Docker, or set the runtime to native:

MCP_DOCTOR_RUNTIME=native task -x mcp:doctor

Expected Output: Layer 2 PASS

PASS check:prereq-runtime - docker reachable
CONFIG .mcp.vc.json servers=5 sha256=8166e12bea11
PASS check:config-declared - 5 server(s) across 1 file(s)
PASS check:config-drift - matches SSOT
PASS check:upgrade-check - no yanked pins
PASS check:readonly-safety - every declared server satisfies its _readonly rule
PASS check:test-l1 - every credential-free uvx/npx server launches --help
PASS server:markitdown - tools/list ok
PASS server:context7 - tools/list ok
PASS server:playwright-automation - tools/list ok
NEEDS-SIGNIN server:github - GITHUB_PERSONAL_ACCESS_TOKEN
PASS check:layer1-gate - no check-level FAIL
PASS check:prereq-claude - claude on PATH
PASS server:azure - tenant=vc roles=Reader
PASS check:readonly-identity - 0 guarded server(s) needs-signin
PASS server:azure - tools/list ok, claude init connected
PASS server:context7 - tools/list ok, claude init connected
PASS server:markitdown - tools/list ok, claude init connected
PASS server:playwright-automation - tools/list ok, claude init connected
SUMMARY layer=2 checks: PASS=3 FAIL=0 SKIP=0 WARN=0 servers: PASS=4 FAIL=0 SKIP=0 NEEDS-SIGNIN=1 total=5 verdict=VERIFIED
EVIDENCE /Volumes/Working/projects/b2b-metering/tmp/b2b-metering/test-results/mcp-verify-l2-vc-20260911T211732Z.json

Variable fields (will differ on your machine): sha256= value, EVIDENCE timestamp and path, tenant= value, servers=<n> count, per-server totals.

Exit Codes

Code	Meaning	Action
0	VERIFIED — checks passed, servers match config	Credential-free servers are reachable. Proceed to Layer 2 if desired.
1	FAILED — one or more checks failed	See the FAIL line for the reason. Fix and retry.
2	Usage error — bad arguments or missing framework	Check the error message and correct the command.
3	NOT VERIFIED — no failures, but no servers tested	All servers need sign-ins. Proceed to Layer 2 or provide credentials.

Troubleshooting

Layer 1 WARN (Platform Not Supported)

A server is marked WARN (not FAIL) if it does not support your host platform:

WARN server:awslabs-iac - linux/amd64 only; install fails on this host (see _platform note)

Fix: This server is unavailable on your platform. Other servers in the list are unaffected.

Layer 2: Tenant Settings File Syntax Error

When running task -x mcp:verify TENANT=<t>, the task loads the tenant's settings file and checks its syntax:

ERROR: tenants/<t>/.env.settings failed shell-syntax check (bash -n)

Fix: The tenant settings file has a shell syntax error. The error message shows the line where the problem is. Correct the syntax, then re-run the task.

Layer 2: READONLY Identity Refused

Layer 2 refuses to start servers if you are signed in with a write-capable identity or if the tenant does not match:

FAIL check:readonly-identity - AWS_PROFILE is not a ReadOnly role

or

FAIL check:readonly-identity - signed-in Azure tenant does not match vc

or

FAIL check:readonly-identity - NOT READONLY-CONFIRMED (Contributor)

Fix: For AWS, sign in with a READONLY profile:

aws sso login --profile <your-READONLY-profile>

For Azure, ensure your account has the Reader role (or a read-only role such as Reader, Billing Reader, or Security Reader). Sign into the correct tenant for the tenant you are verifying (bc or vc).

Docker Image Pull Fails

If you see an image pull error, check your internet connection and Docker registry access, then retry. The doctor caches downloaded packages in Docker named volumes.