← Back to the summary

How Claude Code Connects to the Outside World: Models, Auth, MCP, Editors, and Remote Control

This assistant is not an island. It needs to connect to different companies' AI models, prove your identity, rescue itself when the network fails, connect to external tools and services, be commanded by editors, and even be remotely controlled by a phone. This chapter covers these six things.

7.1 Swapping Brains: Why It Can Use Models from Other Companies

Chapter 1 explained that the model doing the actual thinking runs on a remote server. The problem is: multiple companies offer models, and their "ways of speaking" (request formats, response formats) are all different. Why can this assistant switch to another company's model and still work?

Each Model Company Speaks a Different "Dialect"

The interfaces of different companies' model services vary considerably:

How messages are organized and tools are described in the request—each has its own format;
The structure of the returned streaming data (the event stream discussed in Chapter 3) is completely different;
The field names and meanings for usage statistics (how many tokens were spent) differ;
Some models call "tool invocation" a function call, others call it something else, and the parameter syntax also varies.

If the core loop were directly tied to one company's format, switching models would require rewriting the core loop—a disaster.

The Solution: Deploy Translators at the Boundary

The project's approach (in the independent small package @ant/model-provider) is: the core loop only recognizes one "common language" (the unified events discussed in Chapter 3: message_start / content blocks / deltas / message_stop), and then a translator (adapter) is written for each model company, responsible for translating the "common language" into that company's "dialect" when sending, and translating the returned "dialect" back into the "common language".

Core Loop ──speaks common language──► Translator ──speaks OpenAI dialect──► OpenAI's model
Core Loop ──speaks common language──► Translator ──speaks Gemini dialect──► Gemini's model
Core Loop ──speaks common language──► Translator ──speaks … dialect──► Other models

The translator does three specific things:

Translate Input: Converts the internal message list and tool specifications into the format required by that model;
Translate Output Stream: "Interprets" the streaming data returned by that model into the unified event stream—one says "choices[0].delta", another says "parts[].text", and after translation both become "content block deltas";
Translate the Bill: Converts the different usage fields from each company into a unified calculation of "input tokens, output tokens, cache tokens".

The Power of This Pattern

Zero changes to core code: To add a new model, just write another translator; the core loop, interface, and tool system remain completely untouched;
Some dialects are very similar: Some companies' interfaces deliberately mimic others (for example, some services are compatible with OpenAI's format), so they can directly share the same translator, only changing the address;
Differences are caged: All kinds of bizarre compatibility issues are confined within the translator and do not pollute the main program.

This is the full realization of the design principle emphasized in Chapter 3: translate at the system boundary, keep the interior unified. The tool system, interface, and compression logic are all built on the foundation of "unified event format", and the foundation can be unified precisely because of this adapter layer.

7.2 The Login Matter: How to Prove "You Are You"

Using a model service requires proving your identity first (otherwise, who pays for this call?). The identity verification methods for different services are varied; this chapter sorts them out.

The Simplest: A Key

The most basic method is an API key—a long string of password-like characters. You apply for it on the service provider's website, and the program carries it with every request, equivalent to "saying the password to enter". It's simple and direct, but the downside is that the key must be kept safe; if leaked, others can spend your money.

More Convenient: Account Login (OAuth)

Another method is logging in with your account, similar to "logging into another app with your WeChat account":

1. The program says "login required", opens a browser and jumps to the service provider's login page
2. You log in in the browser and click "Authorize"
3. The service provider sends a "temporary pass" back to the program
   (via a small receiving port temporarily opened locally)
4. The program accesses the service with the pass from then on, without you needing to enter your password again
5. When the pass is about to expire, the program automatically exchanges it for a new one using a "renewal credential", without requiring you to log in again

The pass (access token) has a short lifespan (limited loss if leaked), while the renewal credential (refresh token) has a long lifespan and is stored securely. This is both safe and hassle-free.

Cloud Provider Verification Methods

If the model is deployed on major cloud platforms, the verification methods differ again: some use the cloud platform's own account system (automatically obtaining identity after logging into the cloud platform's command-line tool), others use an access key plus a complex signature algorithm (each request calculates a signature using the key, and the key itself is never sent out). These differences are similarly contained within their respective integration layers; users just log in following the cloud platform's usual method.

Where Credentials Are Stored

The storage of credentials (keys, passes) prioritizes security:

First, store in the operating system's keychain (macOS Keychain, Windows Credential Manager)—this is system-level encrypted storage;
If the system keychain is unavailable, fall back to encrypted file storage;
Passes are automatically refreshed before expiry, transparent to the user.

Unified Login State

Regardless of the underlying method, the program internally maintains a unified "authentication state": who you are, which service you are using, whether the login is valid. Commands like /login and /logout operate on this state. Before any external request is sent, the integration layer automatically attaches the corresponding identity credential; the core loop does not need to care about these details.

7.3 What Happens When Errors Occur: Self-Rescue from Network Jitter, Rate Limiting, and Asking Too Much

Network requests will inevitably fail. A mature assistant cannot just crash on you at the first error; it has a whole set of self-rescue strategies.

First, Classify the Error Type

When the program receives an error, it first classifies it; different errors get different handling:

Error	Plain English	Response
Rate Limit (429)	"You're asking too fast/too much, wait a moment"	Back off and retry according to the wait time specified by the server
Server Busy (529/503)	"I'm overwhelmed over here"	Back off and retry
Network Timeout/Disconnect	The network flickered	Retry
Content Too Long	"The data you stuffed into this question exceeds my capacity"	Compress first, then retry
Authentication Failure	"Who are you? Not recognized"	Prompt to re-login
Model Persistent Errors	This model isn't working right now	Try switching to another model/tier
Illegal Parameters	The request itself is problematic	Don't retry, report the error directly to the user

Backoff Retry: Don't Hammer Relentlessly

When encountering "overwhelmed", you can't retry immediately (that adds fuel to the fire), nor can you wait foolishly. The strategy is exponential backoff: wait 1 second the first time, 2 seconds if it fails, 4 seconds if it fails again… gradually lengthening the interval. Moreover, the server usually explicitly tells you "please wait N seconds" (Retry-After) in the error, and the program strictly complies. There is an upper limit on retries; if exceeded, it gives up and informs the user.

Content Too Long: Auto-Compress Then Retry

If the error is "data exceeds capacity", the program does not fail directly but triggers the compression discussed in Chapter 5 (highlighting key points), freeing up space and then automatically re-asking the question. The user often only feels "it paused for a moment, then continued."

Model Fallback: If This One Doesn't Work, Switch to Another

There is a type of error indicating "the current model has a problem" (for example, the model is temporarily unavailable). The program can automatically switch to a backup model (fallback) to retry—for instance, if the primary model is busy, temporarily switch to another tier model to complete this round of requests. The switch will be indicated on the interface, and you can switch back afterward.

Tool Failure ≠ Conversation Failure

It's especially important to distinguish between two types of failures. Tool execution failure (e.g., command error, file not found) does not count as a system error—the failure information is returned normally to the model as a "tool result". Seeing the error, the model often adjusts itself ("Command doesn't exist? Then I'll try another command"). This is a normal part of the Agent loop and does not need to interrupt the user. Only when "the conversation itself cannot proceed" (network, authentication, model crash) are the above error handling procedures triggered.

Not Concealing Problems

Retries and fallbacks are silent, but when a final failure occurs, it is not hidden: the interface clearly displays the error reason, error code (for easier troubleshooting), and tries to give actionable suggestions ("Please re-login", "Please try again later"). A complete record is also left in the logs.

7.4 External Capabilities: How to Connect to GitHub, Databases, Internal Company Systems

Core tools (reading/writing files, running commands) are built-in, but a vast amount of capability lies externally: operating GitHub, querying databases, sending Slack messages, calling internal company systems… How are these connected? The answer is a standard called MCP (Model Context Protocol).

First, Understand the Problem: Why a Standard is Needed

There are hundreds or thousands of external services. If connecting each one required writing specialized code and specialized adaptations, both sides would suffer—the service side would need to integrate individually for each AI assistant, and the assistant side would need to adapt individually for each service.

MCP is a set of "socket standards" (this analogy was made in Chapter 1): it specifies a unified format for the conversation between "external capability providers" and "AI assistants". Any service that provides its capabilities according to this standard (called an MCP server), and any AI assistant that supports this standard (called an MCP client), can plug together and work, without挑剔挑剔 each other.

GitHub Server ┐
Database Server ├─ All speak MCP, this "common language" ──► Assistant (MCP Client)
Internal Company Service ┘                               Incorporates the tools they provide
                                                        into its own toolbox

What External Capabilities Can Provide

Not just tools; an external service can provide three things:

Tools: Actions that can be executed ("create an issue", "execute an SQL query");
Resources: Data that can be read ("this document", "the structure of this table");
Prompt Templates: Preset common operation workflows.

The assistant incorporates external tools into the toolbox discussed in Chapter 4 (going through the same permission checks) and treats external resources as readable materials.

Three Connection Methods

Local Process: The external capability runs as a local small program (e.g., npx some-service), and the assistant communicates with it via standard input/output. Most common and simplest;
Remote Persistent Connection: Connects to a resident service over the network, suitable for internal enterprise deployment;
Web-style Connection: Communicates via ordinary web requests, suitable for cloud services.

Where Does Configuration Come From: Five Levels

Configuration for which external services to connect can come from five levels, stacked from lowest to highest priority:

Company admin unified push (read-only, employees cannot change)  ← Lowest
Machine-level configuration
Your personal configuration (global, effective for all your projects)
Project-level configuration (stored in the project, shared by the team, committed to git)
Project-level personal override (not committed to git, only effective for your local machine)  ← Highest

This allows an enterprise to control "employees can only use these services", a team to share "our project has connected these services", and an individual to temporarily add their own services, without conflicts.

External Services Also Need Login: Authorization Flow

Many external services require authorization (accessing your GitHub naturally requires your consent). MCP has a built-in standard authorization flow: when the assistant discovers a service requires login, it automatically opens a browser for you to authorize on that service's website. Once authorized, the pass is automatically stored and automatically renewed upon expiry—the same approach as the login mechanism in 7.2.

Security Checks

External tools go through the same permission checks as built-in tools (Chapter 4): if an external tool wants to delete something or send a message, it still asks you. Moreover, external tools are tagged with their source ("This tool is provided by the GitHub service"), so you can clearly distinguish which actions come from built-in capabilities and which from external ones. Admins can also set a "whitelist", only allowing specified services to start.

The Assistant Itself Can Also Be a "Server"

Conversely, the assistant can also package its own capabilities as an MCP server to provide externally, allowing other AI tools to call it. Architecturally, this means "the same set of capabilities can both consume external services as a client and be consumed by others as a server."

7.5 Letting the Editor Command It: How Other Software Talks to It

Chapter 1 mentioned the third form: editors (Zed, Cursor, etc.) can drive this assistant as a backend. This chapter covers the communication rules between them.

The Problem Scenario

Editor vendors want to integrate AI assistant capabilities but don't want to build their own; the assistant wants to be used by editors, but there are many editors. Both sides need a set of communication protocols—similar to how MCP is the standard for "connecting external capabilities", this set is the standard for "Editor ↔ AI Assistant", called ACP (Agent Client Protocol).

How the Conversation Proceeds

The assistant starts in a special mode (no interface, no terminal UI displayed), and then communicates with the editor via "message passing". Messages have a fixed format, similar to this question-and-answer pattern:

Editor: Initialize—I am an editor, I can read/write files, I can open a terminal
Assistant: OK, I am AI Assistant, version X, supporting these capabilities

Editor: New session, working directory is /path/to/project
Assistant: Session created

Editor: The user said this: "Help me refactor this function"
Assistant: (Starts working, continuously reporting progress)
  ├─ I'm thinking… (thought content, streaming)
  ├─ I want to invoke tool: read file xxx
  ├─ I updated the plan: Step 1 in progress…
  └─ I want to execute "run command npm install", need your approval ← Permission request
Editor: (Pops up a dialog asking the user) User approved
Assistant: (Continues) … Done, changes are as follows

Key Point: The Assistant No Longer Draws an Interface, It "Reports Status" Instead

In terminal mode, the assistant draws the interface itself using the techniques from Chapter 6. In ACP mode, the assistant does not draw any interface but reports "what is happening now" to the editor via messages: thinking, what tool is being invoked, where the plan progress is, what needs user approval. The editor takes these statuses and draws them in its own interface style (each editor looks different).

This is why Chapter 1 said "the editor is responsible for the interface, the assistant is responsible for thinking and doing the work."

How Permission Requests Are Handled

When the assistant needs to perform a dangerous operation, it doesn't pop up its own dialog (it has no interface to pop up) but sends a "permission request" message to the editor: "I want to do X, options are: Allow this time / Always allow / Deny this time / Always deny". The editor is responsible for popping up a dialog to the user and then passing the user's choice back. The assistant continues after receiving the choice—the permission model is completely consistent with terminal mode, only the action of "asking the user" is performed by the editor on its behalf.

Visualization of Plan Progress

The assistant's todo plan (TodoWrite from Chapter 4) is also reported via messages: "Plan has 5 steps, Step 2 in progress". The editor renders its own progress bar based on this. The same plan data is drawn in the terminal in terminal mode, and handed to the editor to draw in ACP mode.

An Independent "Relay" Small Program

Sometimes there is a relay program (acp-link) between the editor and the assistant: the editor connects to the relay program, and the relay program is responsible for starting and managing individual assistant processes and forwarding messages. The advantage is that the editor doesn't need to care about how the assistant is installed or started, and the relay program can manage multiple sessions simultaneously. This is also why the assistant needs to support a "no-interface, pure message" mode—it can be driven by any relay layer, any editor.

Difference from the SDK Form

Called directly by a program (the second form in Chapter 1): The caller initiates a conversation using code and gets structured results, suitable for automation scripts;
ACP (the third form): The conversation is designed around "a person operating in front of an editor", with permission dialogs, plan visualization, and streaming thought display, suitable for interactive use.

Both run the same engine (the core loop) underneath.

7.6 Remote Control by Phone: How to Make the Assistant on Your Home Computer Work When You're Out

The final form: a person is outside, using their phone to command the assistant running on their home/office computer.

Why You Can't "Just Run One Directly on the Phone"

The assistant works relying on the environment on your computer: your code, your files, your terminal, your login state. Installing an assistant on a phone, it can't touch the things on your computer. So the correct architecture is: the assistant runs on your computer, and the phone is just a "remote control + display".

Phone (Remote Control/Display)
   │   Network
   ▼
Relay Service (helps connect, because your computer usually doesn't have a public network address)
   │
   ▼
Assistant on Your Computer (the place where the real work happens)

How to Establish the Connection: Scan to Pair

After you start the "remote control" mode at home, a QR code appears on the computer screen. The phone app scans the code to complete pairing. The QR code contains information like the connection address, session identifier, and a temporary public key; the phone and computer establish trust through an encrypted handshake—preventing impersonation.

After successful pairing, you can see the same conversation interface on the phone as in the terminal. You send a message, the message travels all the way back to the assistant at home for execution, and the results are pushed back to the phone in real time.

What You Can Do on the Phone

Watch: Watch the assistant's thinking, output, and tool execution process in real time (streaming push, synchronized with the terminal);
Speak: Send messages, send commands;
Approve: Permission confirmation dialogs for dangerous operations are pushed to the phone; you tap "Allow" on the subway, and the home computer continues execution;
Manage: Can initiate new sessions, view multiple parallel sessions, switch states.

Multiple Devices Watching Simultaneously

Supports multiple devices connected to one session at the same time (phone + tablet + computer screen). State is synchronized across devices: if the model is switched on the computer, the phone also displays the switch synchronously. Permission dialogs are intelligently pushed to the most appropriate device.

A Few Engineering Details

Prevent Sleep: The computer cannot sleep during remote work; the program prevents the system from entering sleep during remote sessions and restores normal behavior after disconnection;
Message Throttling: The assistant can produce a lot of output in one second; pushing everything to the phone wastes data and causes lag. A "throttling gate" merges fragmented messages within a short time (consecutive text fragments merged into one), but key messages (permission requests) are not merged and are pushed immediately;
Code Change Synchronization: When the assistant modifies files, a summary/diff of the changes is pushed to the phone, allowing you to see "what it changed" on the phone, but without transmitting the entire file, saving data;
Security: All communication is encrypted, devices have temporary tokens (valid for a short time), and you can disconnect all remote devices with one click at any time; in remote mode, dangerous operations are more cautious by default (one extra confirmation).

Commonality with Editor Mode

Note the architectural commonality with 7.5: the assistant kernel only cares about "doing work + reporting status"; the terminal interface, editor interface, and phone interface are all "frontends" connected externally. The kernel doesn't care who the results are displayed to or who the permission dialogs are popped up for—this is precisely the fundamental reason why the same engine can drive so many forms.

Chapter Summary

Multi-model relies on adapters: the core only recognizes one unified format; each model gets a translator (translating input, translating output stream, translating the bill); adding a model does not change the core.
Identity verification has two methods: API key and account login. Account login follows "browser authorization + temporary pass + automatic renewal"; credentials are preferentially stored in the system keychain.
Error handling first classifies then self-rescues: rate limiting/busy uses exponential backoff retry; content too long compresses first; model crash switches to a backup model; tool failure is normally fed back to the model for self-correction.
External capabilities use the MCP socket standard: external services provide tools/resources/prompt templates, support local processes and remote connections, configuration is stacked across five levels, external tools go through the same permission checks.
Editors drive the assistant via the ACP protocol: the assistant does not draw an interface but only reports status; permission dialogs and plan progress are handed to the editor for presentation.
Phone remote control is "phone as remote control, computer does the work": scan to pair, encrypted connection, message throttling, sleep prevention, multi-device synchronization.
The main thread running through the whole chapter: unified kernel, translation at boundaries—the same engine, with terminal, editor, and phone all being externally connected frontends.

The next chapter covers data: how state is stored in the program, how conversations are retrieved, how to roll back when something goes wrong, and how billing is calculated.