MCP vs API: Shared Project Reads for Agents

MCP vs API is a question about the client-facing contract, not a choice between two backends. An ordinary HTTP API gives a caller known endpoints and request rules. The Model Context Protocol gives a compatible AI client a way to discover named tools and invoke them with described arguments. An MCP server may use the same API underneath. For a coding agent that needs the current shared project before taking a task, MCP can expose a narrow read tool; a service with a stable integration can call an API directly. Both approaches still need authorization, useful errors, and a reliable source of project data.

This comparison is for engineering teams deciding how coding agents should read shared work. The request and response sketches below are original illustrations, not traffic captured from AppHandoff or instructions to call an undocumented REST endpoint. Protocol behavior is grounded in the official MCP tools specification; the API description comparison follows the OpenAPI Initiative's paths guide. Product-specific behavior follows the current AppHandoff MCP getting-started documentation, checked October 9, 2026.

One task, two client contracts

Imagine an agent resuming work on a shared application. Before editing, it needs to know which project is in scope, which work item is next, and what the agreed task says. A conventional application might offer GET /projects/{id}/tickets?stage=up_next behind an authenticated HTTP API. A caller built for that API already knows its base URL, path, query parameters, response shape, and token policy. Those are application design choices in this illustration, not AppHandoff's published REST contract.

Illustrative HTTP API request, not an AppHandoff endpoint:
GET /projects/example-project/tickets?stage=up_next
Authorization: Bearer <redacted>

Illustrative response:
{ "items": [{ "id": "WORK-12", "title": "Review sign-in flow" }] }

An MCP client instead connects to an MCP server, obtains its available tool descriptions, then calls an appropriate tool with an argument object. For AppHandoff, the documented sequence begins with bootstrap to resolve the project and guidance, followed by find for a list or get for a specific card. Its canonical remote endpoint is https://api.apphandoff.com/mcp. The sketches show tool names and arguments, not complete JSON-RPC wire messages. They use a placeholder project and do not assert that the account has access or that a call has run.

Illustrative AppHandoff MCP tool calls after authorized connection:
{ "name": "bootstrap", "arguments": { "project": "owner/example-project" } }
{ "name": "find", "arguments": { "type": "ticket", "filter": { "stage": ["up_next"] }, "limit": 20 } }

The useful difference is who must know what before the first read. The direct API caller must bring the endpoint contract or an API description. The MCP client can request the server's current tool catalogue and receive names, descriptions, and input schemas. The server still has to implement the underlying read and decide what that identity may see. Discovery reduces hard-coded tool knowledge in a supporting client; it does not supply missing permissions, guarantee the client will choose the right tool, or make the returned work item true.

Discovery and schemas: where the contract lives

The MCP tools specification defines tools/list for discovery and tools/call for invocation. A tool definition includes a unique name, description, and JSON Schema inputSchema; an outputSchema is optional. A client can show or use those descriptions after connecting. This is especially helpful when several agent clients need to read the same project without each team writing a custom endpoint catalogue into prompts. Actual client support and presentation vary, so verify the client you use rather than assuming every AI application understands the server.

An API can also be machine described. OpenAPI defines paths, operations, parameters, request bodies, responses, and security schemes. A generated client or application developer can use that description to build a typed integration. Therefore 'APIs have no schema' is a false distinction. The more precise distinction is that MCP standardizes a tool discovery and invocation conversation for supporting AI clients, whereas an ordinary HTTP API leaves clients to use its own endpoints and whatever description or SDK the provider publishes. One can be translated into the other, but the translation needs design.

For the shared-project read, keep the data contract small. The agent may need a ticket title, stage, revision, and a path to the full body, not an unrestricted dump of every customer record. If the list response is paginated, surface the continuation clearly. If a tool description says 'read' but its implementation writes, the name and schema cannot protect the user. The server's implementation and its authorization checks are the authority. See the MCP server architecture guide for the broader client and server boundary.

Authorization is separate from discovery

The official MCP authorization specification makes authorization optional overall. HTTP implementations that support it should follow its OAuth-based model; stdio implementations should obtain credentials from the environment instead. A server may also impose application-specific access rules. Finding a tool in a catalogue never means the connected identity may read every project or perform every action. With an ordinary API, the caller likewise needs a credential and server-side permission checks. In either design, make the account, project, and action explicit; reject access to the wrong project rather than silently substituting a convenient one.

AppHandoff documents OAuth 2.1 or a personal access token for its MCP endpoint. It says bootstrap can resolve one accessible project or return a choice when several are available. A read may name a project; a write names project_id and follows the server's revision, scope, and approval rules. Its eight served tools are bootstrap, get, find, ticket, plan, message, project, and decide_lifecycle_proposal. The last belongs to a signed-in human's approval card and may not be listed to a client without that support. An agent should not treat it as its own approval shortcut.

A practical read-only rollout is easier to reason about than granting write access at connection time. Connect the intended account, inspect the discovered catalogue, resolve the project, and verify one named read. Only then consider a write tool and the human decision path for actions that need it. The AppHandoff connection guide gives client setup details. Connection success proves neither broad authorization nor task completion.

Errors and recovery differ at the boundary

An ordinary HTTP API can return status codes and a documented error body: for example, unauthorized, missing project, invalid parameter, or a stale revision. Its consumer handles that service's contract. MCP has protocol-level failures and tool-execution failures. The official tools specification describes an unknown tool as a protocol error and a tool execution failure as a result marked isError: true. A transport-level success alone therefore does not mean the requested work succeeded. Read the tool result and any documented structured error fields before retrying.

AppHandoff application-rule refusals include a code, reason, remedy, and retryability. A stale revision asks the client to read current state before deciding whether the intended change still applies. An authenticated token missing a tool scope receives HTTP 200 with isError: true and INSUFFICIENT_SCOPE in its structured result. After an approved OAuth grant change, refresh the token; for a fixed-scope personal access token, obtain a replacement with the needed scope. Repeating the same credential does not add permission. A human-gated lifecycle action yields an approval path for the person; the agent waits for that decision. These are AppHandoff rules, not guarantees that every MCP server has identical error codes or human gates. The MCP Inspector guide shows how to separate connection and tool-call problems.

What does deploying each approach require?

A direct API needs a published contract, authentication, request validation, versioning or change management, capacity limits, observability, and a client that calls it. An MCP surface adds a server endpoint or process, protocol handling, tool descriptions and schemas, result mapping, and a way for each chosen client to connect. The MCP server also needs secure access to the application data or API beneath it. Do not count it as a replacement for the data service, audit trail, or application authorization. It is another maintained boundary.

Keeping an established API underneath can make ownership clearer. The API remains responsible for project reads and business rules; the MCP handler maps a narrowly named tool call to those operations, then returns a bounded result the agent can use. The handler must preserve identity and permission meaning across that mapping. If the API changes a field, the MCP surface needs a contract update and a test. If the tool catalogue changes, a client may need to reconnect to refresh its cached list. These are ordinary integration costs, even when the first demo is only one read call.

Deployment shape depends on transport and client. MCP specifies standard transports, including stdio and Streamable HTTP; a remote team service usually has different operational needs from a local process. AppHandoff's documented URL is a remote HTTP endpoint. A team's own single-purpose script calling one stable API does not gain much from running an MCP server. Conversely, several supported agent clients that must discover the same guarded project reads may benefit from one MCP surface. The official transport specification describes the protocol options.

Choose the smallest interface that serves the caller

• Use a direct API when a known application, service, or script has a stable endpoint contract and can maintain its own client integration.
• Consider MCP when supported AI clients need to discover named capabilities and call the same guarded tools across sessions or products.
• Keep the API beneath MCP when it already owns the project data and business rules; map a narrow tool to it instead of duplicating those rules.
• Begin with a named read, a limited result, and a real access check before exposing mutation tools to an agent client.
• Document how to distinguish transport failure, protocol failure, tool error, and an application-level refusal.

For the shared-project example, a good first decision is simple: what exact question must the next agent answer before editing? If it is 'which approved task is next in this project?', a bounded project and ticket read is enough. If an existing integration already knows that API, use it. If the read must be available as a discoverable tool in multiple supported coding clients, an MCP wrapper is plausible. The cross-client coordination guide covers why the record must outlive one editor session; neither protocol decides task ownership on its own.

After choosing MCP, validate each layer separately. Check the configuration's syntax, connect with the intended account, list the tools the client actually sees, then make a permitted read against a known project. The MCP config checker can examine selected core fields of strict JSON for Claude Code, Cursor, or VS Code in your browser. Use placeholder credentials. It does not contact the server, test OAuth, run a command, or prove full client acceptance. A clean configuration report is a starting point; the connected read is the evidence that the workflow works for that identity.