1.7 - Choosing an Integration Mechanism: MCP, API/CLI, or Agent-to-Agent

Build exercise: Choose and document integration mechanisms for three capabilities

Intermediate · 75 minutes

You'll practice:

• Compare direct tools, CLI access, MCP and A2A against explicit criteria
• Distinguish a stateless tool contract from a stateful agent collaboration
• Apply the platform limits of the MCP connector versus a self-managed MCP client
• Vet a third-party MCP server and constrain it with scope and allowlists
• Write a decision record with exit criteria

1. Define three capabilities and their consumers: (1) an inventory lookup shared by several hosts, (2) an in-process document-merging function used by one app, (3) a partner logistics agent that negotiates delivery windows. State for each whether it is stateless, who owns it and who consumes it.

   The mechanism follows from consumers, ownership and interaction shape, so those facts must be written down before choosing.

   You should see: A three-row table with columns: capability, consumers, owner, stateless or stateful, latency sensitivity, auth needs.

   Hints

   1. Which of the three would still be needed if you added a second consuming application?

   2. Fill the table honestly, including who changes the capability and how often. Note whether the other side reasons about requests.

   3. Example: inventory lookup | 4 apps + Claude Code | inventory team | stateless | moderate | corporate OAuth. Merge function | 1 app | same team | stateless | high | none. Partner agent | our coordinator | partner | stateful, multi-turn | low | cross-org.

2. Score each capability against direct tool, CLI, MCP and A2A on the criteria in the lesson (consumers, coupling, governance, latency, interaction shape, context cost) and pick one primary mechanism each.

   Scoring forces you to justify the choice by criteria instead of habit, and it exposes where two options are close.

   You should see: A scoring grid with a chosen mechanism and a one-sentence reason per capability.

   Hints

   1. Where did the winner lose points, and is that acceptable?

   2. Use 1 to 3 per cell. Expect: inventory to MCP, merge function to direct tool, partner agent to A2A. Write the weakest cell for each winner.

   3. Example reason: inventory lookup -> MCP because four consumers need central OAuth, audit and an operation allowlist; accepted cost is an extra network hop and the server's tool definitions in context.

3. For the MCP choice, write the consumption config twice: a Messages API connector fragment with an allowlist, and a Claude Code project-scope .mcp.json using environment variable expansion for the token. State which of the two can reach a local stdio server.

   The two consumption paths have different capabilities and limits, and exam scenarios test whether you know them.

   You should see: Two JSON fragments and a sentence explaining that the connector needs a remote HTTP endpoint and supports only tools.

   Hints

   1. Which fragment keeps the token out of version control, and how?

   2. The connector uses mcp_servers plus an mcp_toolset with default_config.enabled false and named tools enabled. The .mcp.json uses ${INVENTORY_TOKEN} in a header.

   3. {"mcp_servers":[{"type":"url","url":"https://inventory-mcp.example.com/mcp","name":"inventory","authorization_token":"<from your secret store>"}],"tools":[{"type":"mcp_toolset","mcp_server_name":"inventory","default_config":{"enabled":false},"configs":{"check_availability":{"enabled":true}}}]}
      Project .mcp.json: {"mcpServers":{"inventory":{"type":"http","url":"https://inventory-mcp.example.com/mcp","headers":{"Authorization":"Bearer ${INVENTORY_TOKEN}"}}}}
      The connector needs the beta header mcp-client-2025-11-20 and a remote HTTPS server.

4. Suppose a maintained community MCP server exists for a SaaS tool your team wants. Write the vetting checklist you would apply before connecting it, and the configuration constraints you would put around it.

   Choosing 'use rather than build' is only defensible if you also control the supply-chain and prompt-injection risks that come with third-party servers.

   You should see: A checklist of at least six items and a short list of constraints (scope, allowlist, pinned version, credential scope).

   Hints

   1. What can this server do with the credential you give it, and what content can it inject into the model's context?

   2. Include: list its tools and read the code or source, minimum credential scope, pin the version, restrict to needed tools, run with least privilege or in a sandbox, treat outputs as untrusted, and add it via project scope with review.

   3. Checklist example: 1) tools it exposes reviewed, 2) token scoped to read-only where possible, 3) version pinned, 4) unneeded tools disabled, 5) egress limited, 6) results treated as untrusted, 7) reviewed on each upgrade, 8) listed in the organisation allowlist.

5. Write the decision record for the inventory capability: context, options considered, decision, consequences, and exit criteria that would make you revisit it.

   A decision record is how you defend and later revisit the choice. Exit criteria stop the decision from becoming dogma.

   You should see: A half-page record naming the rejected alternatives and at least three re-evaluation triggers.

   Hints

   1. What would have to change for a direct tool to become the better choice?

   2. Consider consumer count falling to one, latency requirements tightening, tool-definition overhead growing (see Lesson 1.8), or a new MCP specification revision changing the contract.

   3. Example triggers: only one consumer remains; measured server-hop latency breaks the SLO; the server's tool count pushes definitions past the point where deferred loading is needed; the MCP revision changes auth or transport behaviour.