pifini-mcp
Pifini MCP
A thin stdio ↔ HTTPS proxy to Pifini's hosted MCP server — real events, reviewed places, and ticket checkout across the Caribbean & Latin America.
If your MCP client supports remote HTTP servers, you don't need this package at all. Connect directly to:
https://pifini.net/api/mcpThat's a stateless Streamable-HTTP endpoint. This package exists only for clients that speak stdio (a local command + JSON-RPC over stdin/stdout) instead. It has no logic of its own — it reads each request from stdin, forwards it verbatim to the hosted endpoint over HTTPS, and writes the response back to stdout. Nothing here is hardcoded, so every method the hosted server supports (initialize, tools/list, tools/call, ...) works automatically without this proxy needing to know what a "tool" even is.
Install
npx pifini-mcpOr add it to your MCP client's config (Claude Desktop example):
{
"mcpServers": {
"pifini": {
"command": "npx",
"args": ["-y", "pifini-mcp"]
}
}
}Related MCP server: @inbin/mcp
What Pifini's MCP server does
search_events/get_event— search and read real festivals, carnivals, concerts, and cultural events, strongest coverage in the Caribbean and Latin America.search_places/get_place— search reviewed restaurants, bars, venues, attractions, and professionals, including their published reviews.create_ticket_checkout— generate a Stripe-hosted payment link for event tickets. The agent hands the link to its human, who completes payment themselves — agents never see card details.
Read tools are open; no API key required. Full documentation, tool schemas, and a live example live at pifini.net/agents.
Why a proxy package exists at all
Pifini's server is closed-source and hosted (it's part of a larger commercial application), so there's no public repository to point an MCP client's stdio launcher at directly. This package is that missing piece: a small, genuinely open-source (MIT), auditable bridge — not a stand-in for real server code, just the stdio transport Pifini's hosted server doesn't speak natively.
It holds no API keys, no database access, and no business logic. Every request it receives is forwarded byte-for-byte to https://pifini.net/api/mcp (or the URL in PIFINI_MCP_URL, if you want to point it somewhere else for testing) and the response is passed back unmodified.
License
MIT — see LICENSE.
Available Tools
6 toolscreate_ticket_checkoutCreate ticket checkout linkA
Create a secure Stripe-hosted payment link for event tickets. Returns a checkout URL — give it to the human to complete payment themselves; tickets with QR codes are emailed after payment. Get ticket_type_id values from get_event. Always confirm the exact tickets and total with the human before calling this.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Ticket selections | |
| buyer_name | No | Buyer's name (optional) | |
| event_slug | Yes | Event slug | |
| buyer_email | Yes | Email to deliver tickets to (required — ask the human) |
Output Schema
| Name | Required | Description |
|---|---|---|
| event | No | |
| total | No | |
| currency | No | |
| order_id | No | |
| checkout_url | No | |
| instructions | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that tickets are emailed after payment and that the checkout is Stripe-hosted. Annotations only indicate non-read-only and non-destructive, so description adds meaningful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with zero waste, front-loaded with purpose and outcome, followed by usage guidance. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a payment tool requiring human confirmation, the description fully covers purpose, input parameter sources, output (URL), and post-payment flow. Output schema exists per context, so no gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value: explains where to get ticket_type_id (from get_event), specifies quantity range (1-20 not in schema), and flags buyer_email as required with instruction to ask human.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it creates a Stripe-hosted payment link for event tickets and returns a checkout URL. Distinguished from sibling tools (search/get events, places) which are about information retrieval, not payment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to confirm details with the human before calling and to give the URL for self-serve payment. Does not mention when not to use, but context with sibling tools makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_eventGet event detailsARead-onlyIdempotent
Full details for one event by slug: description, venue, date/time, and available ticket types with prices and remaining stock. Use the slug from search_events.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Event slug from search_events |
Output Schema
| Name | Required | Description |
|---|---|---|
| url | No | |
| city | No | |
| slug | No | |
| price | No | |
| title | No | |
| country | No | |
| ends_at | No | |
| summary | No | |
| website | No | |
| category | No | |
| currency | No | |
| starts_at | No | |
| description | No | |
| entry_model | No | |
| ticket_types | No | |
| location_name | No | |
| organizer_url | No | |
| attendee_count | No | |
| organizer_name | No | |
| cover_image_url | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds value by detailing the response contents (available ticket types, prices, remaining stock), which is beyond what annotations cover. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no extraneous words. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description adequately covers the return contents and usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3. The description adds useful context by specifying the slug source ('from search_events'), enhancing the schema's 'Event slug from search_events' description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('event details'), and lists specific data returned (description, venue, date/time, ticket types with prices and stock). It distinguishes from sibling tools like search_events (list) and get_place (different entity).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions using the slug from search_events, providing clear context for when to use this tool. Although it doesn't specify when not to use, the sibling tools list makes alternatives obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_placeGet place details + reviewsARead-onlyIdempotent
Full details for one place by slug, including its most recent published reviews if any exist. listing_type distinguishes a curated entry from an unreviewed directory listing (see search_places) — recent_reviews is often an empty array, which means no reviews yet, not a low-quality place. Use the slug from search_places.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Place slug from search_places |
Output Schema
| Name | Required | Description |
|---|---|---|
| url | No | |
| city | No | |
| name | No | |
| slug | No | |
| type | No | |
| address | No | |
| country | No | |
| summary | No | |
| website | No | |
| category | No | |
| avg_rating | No | |
| price_tier | No | |
| description | No | |
| is_verified | No | |
| is_sponsored | No | |
| listing_type | No | |
| review_count | No | |
| recent_reviews | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by specifying what data is returned (full details, recent reviews) and clarifying field meanings (listing_type, recent_reviews). Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description aligns with them without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise—two to three sentences—front-loaded with the primary purpose, followed by necessary clarifications. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (one required parameter, well-documented schema, annotations, and an output schema), the description covers all necessary aspects: what it does, how to use it (slug from search_places), and key interpretation details (listing_type, empty reviews). It is complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, slug, is fully described in the schema with 'Place slug from search_places,' and the description repeats 'Use the slug from search_places.' Since schema coverage is 100%, the description adds no new semantic information, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details for one place by slug, including recent reviews, and distinguishes itself from search_places by specifying that the slug comes from that tool. The title 'Get place details + reviews' reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to 'Use the slug from search_places,' providing clear context for when to use this tool. It also addresses a common misinterpretation about empty recent_reviews. While it does not explicitly list when not to use it or name alternatives like get_event, the guidance is sufficient for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_categoriesList place categoriesARead-onlyIdempotent
Discover valid category values for search_places. Pifini's places directory uses Overture Maps' taxonomy — over 1,000 specific values like caribbean_restaurant, church_cathedral, landmark_and_historical_building — rather than broad buckets, so guessing a category string will usually miss. Call this first with a rough query (e.g. 'coffee' or 'beach') to find the exact value, then pass it to search_places' category parameter.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results, 1-100 (default 30) | |
| query | No | Rough term to match against category values, e.g. 'coffee', 'beach' | |
| country | No | ISO-3166 alpha-2 country code — only return categories present in that country |
Output Schema
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| categories | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it uses Overture Maps taxonomy with over 1,000 specific values, and that guessing will usually miss. This explains why the tool is needed and what it returns, beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph but is front-loaded with the purpose, followed by context and usage instruction. Every sentence adds value; no fluff. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists (so return values are covered), the description is complete. It explains why the taxonomy is needed, how to use the tool, and how to pass results to search_places. The only minor gap is no explicit mention of 'limit' behavior, but schema covers that. Overall comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter has a schema description. The description adds meaning by explaining that 'query' is a 'rough query' (partial match) and that 'country' filters by country presence. This aids understanding beyond raw schema, though the description does not detail every parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's purpose: 'Discover valid category values for search_places.' It uses a specific verb (discover) and resource (category values), and distinguishes itself from sibling tools like search_places by acting as a preparatory step. Examples of specific category values further clarify the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: 'Call this first with a rough query... then pass it to search_places' category parameter.' It contrasts with guessing, providing clear context for usage. No alternative tool is mentioned, but the recommendation is direct and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_eventsSearch eventsARead-onlyIdempotent
Search upcoming events (festivals, carnivals, concerts, food + cultural events) across the Caribbean, Latin America, and beyond. Returns event names, dates, locations, category, price (when known), and page URLs. Strongest coverage: Barbados, Trinidad, Jamaica, Bahamas, Mexico.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City name filter | |
| limit | No | Max results, 1-50 (default 10) | |
| query | No | Free-text search over title and description | |
| offset | No | Skip this many matching results (for paging past the limit) | |
| country | No | ISO-3166 alpha-2 country code, e.g. BB, TT, JM | |
| category | No | Filter by event category | |
| near_lat | No | Latitude to search near (pair with near_lng) | |
| near_lng | No | Longitude to search near (pair with near_lat) | |
| radius_km | No | Search radius in km around near_lat/near_lng (default 25, max 500) | |
| entry_model | No | Filter by how someone gets in: 'free' = confirmed free entry, 'ticketed' = Pifini sells tickets, 'external' = paid but sold elsewhere, 'mixed' = umbrella event with both free and paid components, 'unknown' = not yet confirmed either way. | |
| include_past | No | Include past events (default false) | |
| starts_after | No | Only events starting on/after this date, e.g. '2026-08-01' or a full ISO timestamp | |
| starts_before | No | Only events starting on/before this date, e.g. '2026-08-31' or a full ISO timestamp |
Output Schema
| Name | Required | Description |
|---|---|---|
| count | Yes | Number of events in this page of results |
| events | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, idempotentHint, destructiveHint; description adds coverage strengths and output fields. It does not mention default pagination or that past events are excluded by default (handled via schema). Adds context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: scope, return fields, coverage. No fluff, front-loaded with core purpose. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complex schema (13 params, 2 enums, output schema, annotations), the description covers overall function, return fields, and regional strengths. Lacks explicit note on default date-range behavior but schema handles it. Good for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 13 parameters are already described with schema descriptions (100% coverage). The description adds minimal extra meaning (only geographical strength hint). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('search upcoming events') and resource ('events'), listing return fields and geography. It clearly distinguishes from siblings like get_event (single event) and search_places (places).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use (searching upcoming events in covered regions) but does not explicitly exclude cases or name alternatives; the context of sibling tool names provides implicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_placesSearch places and businessesARead-onlyIdempotent
Search Pifini's places directory across the Caribbean and Latin America — restaurants, bars, beaches, attractions, venues, hotels, tour operators, professionals, and services. Every result carries listing_type: 'curated' is a small, editorially reviewed set of flagship entries; 'directory' is the much larger set sourced from open map data (name, category, location, contact info) that has no reviews yet — say so rather than implying a recommendation the data doesn't back up. Category is a specific Overture taxonomy value (e.g. caribbean_restaurant, church_cathedral), not a broad bucket — call list_categories first if unsure of the exact value. Results marked is_sponsored are paid placements — disclose that when recommending.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City name filter | |
| limit | No | Max results, 1-50 (default 10) | |
| query | No | Free-text search over name and summary | |
| offset | No | Skip this many matching results (for paging past the limit) | |
| country | No | ISO-3166 alpha-2 country code | |
| category | No | Filter by exact category value (e.g. 'caribbean_restaurant'). Use list_categories to discover valid values — there are 1,000+, not a small fixed set. | |
| near_lat | No | Latitude to search near (pair with near_lng) | |
| near_lng | No | Longitude to search near (pair with near_lat) | |
| radius_km | No | Search radius in km around near_lat/near_lng (default 25, max 500) | |
| entity_type | No | Filter by broad type of place |
Output Schema
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| places | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description enriches transparency by detailing result types (curated vs. directory) and the need to avoid implying recommendations for directory entries, plus disclosure of sponsored placements. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that conveys purpose and key nuances. It is front-loaded and efficient, though slightly verbose. Could be streamlined but avoids unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 params, output schema exists), the description covers critical behavioral aspects (listing types, sponsored results) and refers to list_categories. It does not explain pagination parameters in detail, but schema covers that. Acceptably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains all parameters. The description adds only minor extra context (e.g., repeating the list_categories suggestion for category) but does not significantly enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches Pifini's places directory across the Caribbean and Latin America, listing specific categories (restaurants, bars, etc.). It distinguishes itself from siblings like search_events, get_place, and list_categories by focusing on places search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance: advises calling list_categories before using the category filter and discloses how to handle sponsored results. However, it does not explicitly state when not to use this tool (e.g., for events) or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
6 tool updates
- First observed
create_ticket_checkout - First observed
get_event - First observed
get_place - First observed
list_categories - First observed
search_events - First observed
search_places
TDQS
Scored across 6 tools
Each tool targets a distinct function: searching vs. getting details for events and places, listing categories, and creating a checkout. There is no overlap or ambiguity between any pair of tools.
All tool names follow a consistent verb_noun pattern in snake_case: search_events, get_event, search_places, get_place, list_categories, create_ticket_checkout. This makes the surface predictable and easy to navigate.
With 6 tools, the set is well-scoped for the server's purpose—covering both events and places with search, detail retrieval, and a checkout action. It is neither too sparse nor overly dense.
The tools cover the full consumer workflow: discover events/places, get full details, and purchase tickets. The supporting list_categories tool fills a potential gap in place search. No obvious missing operations for the stated domain.
Maintenance
Related MCP Connectors
Query SEC EDGAR filings, XBRL financials, and company data through MCP. STDIO & Streamable HTTP.
The official Planning Center MCP server for interacting with your ministry's data.
Host your MCP tool over streamable HTTP in one command.
The official MCP Server for the Mux API
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA thin stdio proxy to Quantustik's hosted MCP server, providing live S&P 500 signals, forecasts, and market data for MCP clients that only support local stdio servers.27 npmMIT
- AlicenseNot gradedqualityCmaintenanceProxies stdio MCP clients to Inbin's remote MCP endpoint, exposing tools to list inboxes, search and retrieve events, and inspect schemas.16 npm1MIT
- AlicenseCqualityBmaintenanceMinimal MCP server exposing the Connectif HTTP API to MCP clients over stdio, enabling operations like contacts, purchases, products, exports, imports, workflows, and more.123 npmMIT
- AlicenseAqualityAmaintenanceZero-dependency stdio bridge to Moltline Studio's fleet of 14 hosted MCP servers covering code review, time operations, data transforms, business ops, education, research, outreach and more. Free tier requires no registration; premium tools unlock with a license. Independently audited, MCPize Verified A.210MIT