# Composite Service

> Wrap multi-step API workflows into a single MCP tool so the agent calls one thing instead of chaining five raw endpoints.

- **Category**: Agentic AI
- **Subcategory**: Tool Use & Environment
- **Canonical URL**: https://designpattern.fyi/patterns/composite_service_mcp/

---

## Description
**Intent**: Expose task-level capabilities to the agent, not low-level HTTP endpoints.

**Context**: You're building an MCP server over a set of fine-grained APIs. Agents trying to 'create project, set env vars, deploy' currently chain three separate calls — and get it wrong half the time because ordering matters and error handling is inconsistent.

**Solution**: Identify recurring multi-call workflows and expose each as one MCP tool. The handler performs the calls, threads intermediate results, and returns a single typed result. `deploy_project` internally creates the project, sets env vars, and triggers deployment. Keep each composite cohesive (one business capability per tool) and define explicit partial-failure semantics so the tool reports exactly which underlying call failed.


## Use Cases
- Common tasks span several endpoints in a fixed order.
- A one-to-one tool surface is too large or too chatty for reliable tool selection.
- Orchestration logic is stable enough to own server-side and reuse across tasks.
- Partial-failure handling should be consistent, not re-derived by the model each time.





## Trade-offs


### Advantages

- Smaller tool surface — the model picks among task-level capabilities, not raw endpoints.

- Fewer round-trips and lower token cost per task.

- Orchestration lives on the server where it's reusable, testable, and versioned.

- Partial failures resolve inside the tool with consistent semantics.




### Considerations & Drawbacks

- The server holds more logic — more to maintain and version.

- Bundled endpoints are coupled; one upstream API change can break the composite.

- Over-aggregation creates opaque mega-tools that are a nightmare to debug.

- Bundled pieces are harder to reuse individually than separate tools.







---
**Reference**: [Original Source](https://www.agentpatternscatalog.org/patterns/composite-service-mcp/)