Choose operations with a clear result
A generic update-record tool leaves the agent to assemble business logic itself. A prepare-quote or find-available-slots operation can express the intended result directly. Define required inputs, validation, output fields and error cases. Prefer a smaller set of coherent operations over exposing every endpoint merely because it exists in the application.
Reuse authorization inside the application
An agent acts for a particular identity and organization. Its API credential should not become an all-customer administrator. Call the same business services and permission checks used by the normal application. Test access to another customer’s records and an operation outside the granted scope. Naming an endpoint “safe” does not enforce the boundary.
Plan retries and ambiguous outcomes
A request may time out after the application has completed the action. Without a stable operation identity, retrying could duplicate a booking. Define which actions accept an idempotency key and how an existing result is returned. Distinguish a validation failure from an unknown delivery outcome. The client should have a way to retrieve status instead of blindly repeating a write.
Add the protocol only after the contract
An HTTP API and an MCP interface can serve different integration needs. Neither should duplicate or weaken the underlying business logic. In a Forge Project, specify the required client, operation surface and acceptance examples first. Then implement the appropriate adapter and documentation. The customer retains the software and controls who receives credentials after deployment.
Expose a business operation, not an unrestricted database
An assistant helping with appointments needs “find available slots” and perhaps “prepare a rescheduling draft”. It does not need a generic SQL tool. Define each operation around the business job, with typed input, a meaningful result and explicit access scope. The application should reuse its existing authorization and business services.
Keep read, draft and committed actions distinct. A draft operation can return the proposed changes and required approval. The final action rechecks availability and permission against current data. Documentation should state how repeated requests are handled and how the caller recognizes an uncertain outcome.
| Decision | Useful requirement | Evidence |
|---|---|---|
| Read slots | Filter by permitted office and date. | No records from other scopes. |
| Draft move | Return a proposal without changing a booking. | No database write or notification. |
| Commit move | Recheck permissions and freshness. | One audited effect with repeat protection. |
Where this goes wrong
Adding an MCP interface does not remove these responsibilities. It describes how a supported client discovers and calls tools; it is not permission to bypass application policy. Scope tokens to the intended operations and revoke them independently.
A good agent interface makes the permitted work easy and the forbidden work impossible at the server.
Turn it into a working checklist
- Name business outcomes.
- Scope every credential.
- Test forbidden operations.
- Handle duplicate and unknown outcomes.
A concrete next step
Hand over an operation catalog, authorization matrix, example requests and negative tests. Keep the interface versioned so an external agent does not silently rely on changed semantics.
Watch a related case
The video could not be loaded. Try again later.