Copy page

Build with Cafecito

Cross-product Workflow

Use Beans when you need what publishers published. Use Espresso when you need what happened, what it may mean, and what supports that claim. One API key authenticates both REST and both MCP servers.

Tool names match the hosted MCP catalogs on MCP and AI agents. Shared transport rules live on API conventions.

When to stay on one product

User intent	Stay on
Article URLs, titles, summaries, available full content, social media engagements, similar articles	Beans only
Story across publishers and article clusters	Beans only (listStories → getStory → listStoryArticles)
Publisher metadata for Beans filters	Beans listSources / getSource
Concrete developments (what happened)	Espresso searchEvents / getEvent
Meaning, impact, outlook	Espresso searchSignals / getSignal
Supporting records and available URLs for a selected Event	Espresso getEventEvidence
Intelligence source provenance	Espresso listIntelligenceSources / getIntelligenceSource

Beans Story tools do not return Espresso Events. Espresso evidence is not a Beans article search.

Beans → Espresso evidence sequence

Run this when the user starts from publisher coverage and then needs structured confirmation or supporting records.

1. Find publisher coverage (Beans).
   Use searchArticles, getLatestArticles, getTopHeadlines, getTrendingArticles, or listStories. Optionally narrow with discovery tools (listCategories, listEntities, listRegions, listSentiments).

2. Select identifiers (Beans).
   Take data[].id for Articles or Stories. Call getArticle for a selected Article UUID. For a Story, call getStory then listStoryArticles if member Articles are required. Keep canonical Article url values for citation.

3. Formulate the intelligence question (Espresso).
   Copy the topic, entity names, and region names the user (or the selected Articles) actually used. Do not assume a Beans Article UUID is an Espresso Event UUID.

4. Search what happened (Espresso).
   Key points, events → searchEvents (GET /espresso/events). Discover exact filters with listIntelligenceEntities, listIntelligenceRegions, listIntelligenceEventTypes, and fuzzy tags with listIntelligenceTags when spelling is unknown.

5. Get more details on what happened (Espresso).
   Call getEvent or getSignal for the chosen data[].id. Walk links with getEventSignals or getSignalEvents when the question needs both facts and conclusions.

6. Understand the broader causal chain, impacts and forecast (Espresso).
   Call searchSignals (GET /espresso/signals). Discover exact filters with listIntelligenceEntities, listIntelligenceRegions, listIntelligenceEventTypes, and fuzzy tags with listIntelligenceTags when spelling is unknown.

7. Inspect evidence tracing (Espresso).
   After an Event UUID, call getEventEvidence (GET /espresso/events/{event_id}/evidence). Use returned identity, creation time, tags, Source IDs, and available URLs. An empty data array means no evidence records are available for that Event under the supplied filters—not a Beans miss.

8. Cite both layers.

   • Publisher reading: Beans Article url (and Story membership if used).
   • Structured claim: Espresso Event/Signal IDs plus evidence URLs and getIntelligenceSource when provenance metadata is required.

9. Paginate independently.
   Beans and Espresso cursors are not interchangeable. Send each product's pagination.next_cursor unchanged on the same route or tool.

Complete composite client

The following programs are complete, copy-pasteable handoffs: they search publisher coverage in Beans, search concrete developments and interpretations in Espresso, then retrieve evidence for the first selected Event. Set CAFECITO_API_KEY before running. Each product keeps its own returned IDs and pagination envelope.

Node 18+ provides fetch; the Python program requires the requests package. The output keeps publisher Article URLs for citation and Espresso Event/Signal IDs plus evidence records for structured support.

REST equivalents for the handoff

Step	MCP tool	REST
Publisher search	searchArticles	GET /beans/articles/search
Story cluster	listStories / getStory / listStoryArticles	GET /beans/stories, GET /beans/stories/{id}, GET /beans/stories/{id}/articles
Article detail	getArticle	GET /beans/articles/{id}
What happened	searchEvents / getEvent	GET /espresso/events, GET /espresso/events/{event_id}
Evidence	getEventEvidence	GET /espresso/events/{event_id}/evidence
Outlook	searchSignals / getSignal	GET /espresso/signals, GET /espresso/signals/{signal_id}

Health checks remain REST-only: GET /beans/health and GET /espresso/health without a key.

Agent checklist

• Same Bearer key on https://api.cafecito.tech/beans/mcp and https://api.cafecito.tech/espresso/mcp.
• Never pass a Beans Article or Story UUID into Espresso path parameters.
• Never answer “what does this mean?” from Beans Article text alone when Espresso Signals are in scope.
• Never answer “what did this publisher print?” from Espresso Events alone when Beans Articles are in scope.
• Do not invent tools outside the MCP catalog.