MCP Integration Guide
Complete guide to connecting AI tools to Avena Terminal via the Model Context Protocol. Setup instructions, code examples, tool documentation, and troubleshooting.
What is MCP?
The Model Context Protocol (MCP) is an open standard created by Anthropic that allows AI assistants to connect to external data sources and tools. It works like a USB-C port for AI: a universal interface that lets any compatible AI tool access any compatible data source. Avena Terminal implements MCP via Streamable HTTP transport at avenaterminal.com/mcp, providing 7 property intelligence tools with no authentication required. Any MCP-compatible client can connect and immediately access live scored data for new build properties across Spain.
Available Tools (7)
search_properties
Search and filter properties across the 27 EU markets by country, region, price range, property type, minimum score, bedroom count, and beach distance. Returns APIP v1 format when format="apip".
| Parameter | Type | Description |
|---|---|---|
| country | string | ISO 3166-1 alpha-2 country code (e.g. "ES", "PT", "FR", "DE", "NL", "IT") |
| region | string | Costa/region slug (e.g. "costa-blanca", "costa-del-sol") |
| town | string | Town name or slug |
| type | string | Property type: villa, apartment, penthouse, townhouse, bungalow |
| min_price | number | Minimum price in EUR |
| max_price | number | Maximum price in EUR |
| min_score | number | Minimum Avena Score (0-100) |
| min_beds | number | Minimum bedrooms |
| max_beach_km | number | Maximum distance to beach in km |
get_property
Get full details for a specific property including Avena Score breakdown, yield estimate, developer info, and images.
| Parameter | Type | Description |
|---|---|---|
| ref | string | Property reference ID |
get_market_stats
Get aggregate market statistics for a region or the entire market. Includes averages, distributions, and top towns.
| Parameter | Type | Description |
|---|---|---|
| region | string | Optional costa slug to filter by region |
get_top_deals
Get the highest-scoring properties currently available, ranked by Avena Score.
| Parameter | Type | Description |
|---|---|---|
| limit | number | Number of results (default 10) |
| type | string | Optional property type filter |
estimate_roi
Project returns over a holding period, accounting for rental income, appreciation, and costs.
| Parameter | Type | Description |
|---|---|---|
| ref | string | Property reference ID |
| hold_years | number | Holding period in years (default 5) |
| appreciation_pct | number | Annual appreciation assumption (default 3%) |
compare_alternatives
Find and compare similar properties to a given reference, showing side-by-side metrics.
| Parameter | Type | Description |
|---|---|---|
| ref | string | Property reference ID to compare against |
| limit | number | Number of alternatives (default 5) |
market_timing
Assess whether current conditions in a region favour buyers or sellers based on inventory, pricing, and demand.
| Parameter | Type | Description |
|---|---|---|
| region | string | Costa slug to analyse |
Step-by-Step Setup
Claude Desktop
File: claude_desktop_config.json · Path: ~/Library/Application Support/Claude/ (Mac) or %APPDATA%\Claude\ (Windows)
Steps
- 1.Open Claude Desktop settings
- 2.Click "Developer" then "Edit Config"
- 3.Paste the JSON below into your config file
- 4.Restart Claude Desktop
- 5.Ask Claude: "Search for villas under 300k on Costa Blanca"
Config
{
"mcpServers": {
"avena-terminal": {
"url": "https://avenaterminal.com/mcp"
}
}
}Cursor
File: .cursor/mcp.json · Path: Project root or ~/.cursor/
Steps
- 1.Create or edit .cursor/mcp.json in your project root
- 2.Paste the config below
- 3.Restart Cursor or reload the window
- 4.Use Avena tools in Cursor chat or Composer
Config
{
"mcpServers": {
"avena-terminal": {
"url": "https://avenaterminal.com/mcp",
"transport": "http"
}
}
}Windsurf
File: mcp_config.json · Path: ~/.codeium/windsurf/
Steps
- 1.Navigate to ~/.codeium/windsurf/
- 2.Create or edit mcp_config.json
- 3.Paste the config below
- 4.Restart Windsurf
- 5.Avena tools will be available in Cascade
Config
{
"mcpServers": {
"avena-terminal": {
"serverUrl": "https://avenaterminal.com/mcp"
}
}
}Cline (VS Code)
File: Cline MCP Settings · Path: VS Code > Cline Extension > MCP Servers
Steps
- 1.Open VS Code with Cline extension installed
- 2.Go to Cline settings > MCP Servers
- 3.Add a new server with the config below
- 4.Save and the tools will appear in Cline
Config
{
"mcpServers": {
"avena-terminal": {
"url": "https://avenaterminal.com/mcp",
"transportType": "streamable-http"
}
}
}Code Examples
Python
pip install langchain-mcp-adapters langchain-anthropic
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langchain_anthropic import ChatAnthropic
async def main():
model = ChatAnthropic(model="claude-sonnet-4-20250514")
async with MultiServerMCPClient({
"avena-terminal": {
"url": "https://avenaterminal.com/mcp",
"transport": "streamable_http",
}
}) as client:
# List available tools
tools = client.get_tools()
print(f"Connected! {len(tools)} tools available")
# Create agent and query
agent = create_react_agent(model, tools)
result = await agent.ainvoke({
"messages": [{
"role": "user",
"content": "Find the top 5 villas under 350k with highest Avena Score"
}]
})
print(result["messages"][-1].content)
asyncio.run(main())JavaScript / TypeScript
npm install @modelcontextprotocol/sdk
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
const client = new Client({ name: "my-app", version: "1.0.0" });
const transport = new StreamableHTTPClientTransport(
new URL("https://avenaterminal.com/mcp")
);
await client.connect(transport);
// List available tools
const { tools } = await client.listTools();
console.log(`Connected! ${tools.length} tools available`);
// Search properties
const result = await client.callTool({
name: "search_properties",
arguments: {
region: "costa-blanca",
max_price: 300000,
min_score: 60,
type: "villa"
}
});
console.log(result.content);
// Get market stats
const stats = await client.callTool({
name: "get_market_stats",
arguments: { region: "costa-blanca" }
});
console.log(stats.content);
// Estimate ROI
const roi = await client.callTool({
name: "estimate_roi",
arguments: { ref: "PROP-001", hold_years: 5 }
});
console.log(roi.content);curl
No dependencies required
# List available tools
curl -X POST https://avenaterminal.com/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
# Search properties
curl -X POST https://avenaterminal.com/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search_properties",
"arguments": {
"region": "costa-blanca",
"max_price": 300000,
"min_score": 60
}
},
"id": 2
}'
# Get top deals
curl -X POST https://avenaterminal.com/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_top_deals",
"arguments": { "limit": 5 }
},
"id": 3
}'
# Get market stats
curl -X POST https://avenaterminal.com/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_market_stats",
"arguments": { "region": "costa-del-sol" }
},
"id": 4
}'
# Market timing assessment
curl -X POST https://avenaterminal.com/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "market_timing",
"arguments": { "region": "costa-blanca" }
},
"id": 5
}'Example Tool Calls & Responses
search_properties
Request
{
"name": "search_properties",
"arguments": {
"region": "costa-blanca",
"max_price": 250000,
"type": "apartment",
"min_score": 65
}
}Response (abbreviated)
{
"total": 42,
"results": [
{
"ref": "CB-APT-1234",
"type": "Apartment",
"location": "Torrevieja",
"price": 189000,
"score": 78,
"yield_gross": 6.8,
"bedrooms": 2,
"built_m2": 75,
"beach_km": 0.8
},
...
]
}estimate_roi
Request
{
"name": "estimate_roi",
"arguments": {
"ref": "CB-APT-1234",
"hold_years": 5,
"appreciation_pct": 3
}
}Response (abbreviated)
{
"property": "CB-APT-1234",
"purchase_price": 189000,
"hold_years": 5,
"gross_rental_5yr": 64260,
"appreciation_5yr": 29925,
"total_return_pct": 49.8,
"annualised_return": 8.4,
"estimated_exit_price": 218925
}market_timing
Request
{
"name": "market_timing",
"arguments": {
"region": "costa-blanca"
}
}Response (abbreviated)
{
"region": "Costa Blanca",
"assessment": "balanced",
"buyer_score": 62,
"inventory_level": "adequate",
"price_trend": "stable",
"demand_indicator": "moderate",
"recommendation": "Selective buying recommended. Focus on properties scoring 70+ on the Avena Score."
}Troubleshooting
Connection refused or timeout
Verify https://avenaterminal.com/mcp returns JSON with a GET request. Check your internet connection and any firewall/proxy settings.
Tools not appearing in Claude Desktop
Ensure your claude_desktop_config.json is valid JSON. Restart Claude Desktop completely (quit and reopen, not just close the window).
Transport error in Cursor
Make sure transport is set to "http" (not "sse" or "stdio"). Cursor uses HTTP transport for remote MCP servers.
Empty results from search
Broaden your search criteria. Try removing filters one at a time. Use get_market_stats first to understand available data ranges.
CORS errors in browser
The MCP endpoint supports CORS with Access-Control-Allow-Origin: *. If using from a browser, ensure you are making POST requests to /mcp.
Invalid JSON-RPC response
Ensure your request follows JSON-RPC 2.0 format with jsonrpc, method, params, and id fields. The method should be "tools/call" or "tools/list".
Smithery installation fails
Try: npx @anthropic-ai/create-mcp-server or install directly via the JSON config instead of Smithery CLI.
Rate limiting
The Avena Terminal MCP endpoint has generous rate limits. If you hit limits, add a small delay between calls. No API key needed.
Smithery Listing
Avena Terminal is listed on Smithery, the MCP server registry. Install with one command:
smithery mcp add henrik-kmvv/avena-terminal
View the listing at smithery.ai/server/@henrik-kmvv/avena-terminal