Copy page

General

MCP Integration

Every Cafecito API product ships an MCP (Model Context Protocol) server — same auth, same key, zero extra setup. Point your AI agent or MCP client at the endpoint and go.

Authentication

Get API Key

Connecting to MCP Servers

Server URL: https://api.cafecito.tech/<product>/mcp

Code
Authorization: Bearer YOUR-API-KEY

Beans MCP server

Server URL: https://api.cafecito.tech/beans/mcp (v0.8)

Recommended agent workflow: discover tag values → search the corpus → use time-ordered feeds → resolve publisher IDs → track story propagation.

Tool	REST path	Purpose
listCategories	GET /beans/tags/categories	Discover exact category filter values
listEntities	GET /beans/tags/entities	Discover exact entity filter values
listRegions	GET /beans/tags/regions	Discover exact region filter values
searchArticles	GET /beans/articles/search	Primary full-corpus search
getLatestArticles	GET /beans/articles/latest	Newest articles (reverse chronological)
getTrendingArticles	GET /beans/articles/trending	Trending by engagement score
getTopHeadlines	GET /beans/articles/top-headlines	Top headlines from last 24 hours
getPublishers	GET /beans/sources	Resolve publisher source metadata
getArticlePropagation	GET /beans/articles/propagation	Track story spread (CSV URLs)
postArticlePropagation	POST /beans/articles/propagation	Track story spread (JSON body)

See the Beans howto for parameters, response shapes, and examples.

Code
# openai-agents.HostedMCPTool (https://github.com/openai/openai-agents-python)
import os
import asyncio
from agents import Agent, HostedMCPTool, Runner

mcp_tool_config = {
    "type": "mcp",
    "server_label": "cafecito_beans",
    "server_url": "https://api.cafecito.tech/beans/mcp",
    "authorization": os.getenv("CAFECITO_API_KEY"),    
    "require_approval": "never",
}

# SETUP: model client using AsyncOpenAI
# SETUP: model using OpenAIChatCompletionsModel

agent = Agent(
    name="News Analyst",
    instructions="EXTRACT news headlines and associated briefings",
    tools=[
        HostedMCPTool(tool_config=mcp_tool_config)
    ],
)

PROMPT_TEMPLATE = """
Today: {date}
Question: What is trending on middle east today?
"""
  
result = Runner.run_sync(agent, PROMPT_TEMPLATE.format(date=datetime.now().strftime("%Y-%m-%d")))
print("=== Final output ===")
print(result.final_output)

Espresso MCP server

Server URL: https://api.cafecito.tech/espresso/mcp (v0.1)

Tool	REST path	Purpose
searchEvents	GET /espresso/events	Search event-kind sips
searchSignals	GET /espresso/signals	Search signal-kind sips
listTags	GET /espresso/tags	List tags for filtering events and signals
getRelatedSips	GET /espresso/related/{relationship}	Traverse same_as or derived_from links

Use response_type=text on list endpoints when feeding results directly to LLM context — same data, fewer tokens than JSON.

See the Espresso howto for the data model, text format, and examples.

Use cases

• AI assistants and RAG workflows that need fresh news context (Beans)
• Business intelligence agents monitoring events, signals, and cross-domain outlooks (Espresso)
• AI agents that monitor trends, entities, or topics in real time
• LLM pipelines that require enrichment-ready JSON or token-efficient plain text, not raw HTML

Related

• Beans howto
• Espresso howto
• Cafecito
• Pricing
• Contact