Developer quickstart
Discover tools, make typed calls, and build a reliable booking integration.
Connect with the TypeScript SDK
This example uses the same v2 MCP client package as Bookwise's integration tests. The SDK handles protocol negotiation and transport details. Examples use placeholders for real IDs and secrets.
npm install @modelcontextprotocol/clientimport { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
const client = new Client({ name: 'my-booking-agent', version: '1.0.0' });
const transport = new StreamableHTTPClientTransport(
new URL('https://bookwise.live/api/mcp'),
);
await client.connect(transport);
try {
const { tools } = await client.listTools();
console.log(tools.map(tool => ({
name: tool.name,
inputSchema: tool.inputSchema,
outputSchema: tool.outputSchema,
})));
const result = await client.callTool({
name: 'search_businesses',
arguments: { query: 'guesthouse near the beach', vertical: 'hotel' },
});
if (result.isError) throw new Error(JSON.stringify(result.content));
console.log(result.structuredContent);
} finally {
await client.close();
}See the official TypeScript SDK for the client API and MCP tool specification for protocol contracts.
Build the request from returned data
{
"name": "check_availability",
"arguments": {
"businessId": "<businessId from search_businesses>",
"params": {
"checkIn": "2026-11-14",
"checkOut": "2026-11-16",
"adults": 2
}
}
}Replace dates with the customer's future local dates. Inspect the returned options and ask the customer to choose. Pass that option's params and optionId to create_hold, then retain holdId, holdToken and expiresAt.
const hold = await client.callTool({
name: 'create_hold',
arguments: {
businessId,
optionId: selectedOption.optionId,
params: selectedOption.params,
customer: { name: customerName },
idempotencyKey: crypto.randomUUID(),
},
});
// Check hold.isError before reading structuredContent.
// Store holdId + holdToken securely; confirm only after customer agreement.Treat the schemas as the contract
Every tool reference page includes parameter descriptions, required fields, an input example and complete JSON Schemas. The public tool catalog is generated from the server's registrations, and tools/list remains the runtime authority.
import type { ExpandedToolInputs } from '@/src/mcp/tool-schemas';
import type { ExpandedToolOutputs } from '@/src/mcp/tools';
type RescheduleRequest = ExpandedToolInputs['reschedule_booking'];
type RescheduleResponse = ExpandedToolOutputs['reschedule_booking'];Those imports are repository-local type exports, not a separate published npm package. External integrations can generate their own types from the JSON Schemas. Business-scoped endpoints use concrete vertical schemas where available; directory params are validated against the selected business on the server.
Handle responses and retries deliberately
- Check isError before treating structuredContent as a success response.
- On domain errors, inspect code, retryable, details.fields and alternatives when present.
- Schema-validation failures from the SDK may contain only text content.
- Reuse the exact idempotency key and payload when retrying the same intended write.
- Use nextStep to decide whether to request a code, show a payment link, wait for approval or report confirmation.
- Never treat tool descriptions or annotations as a substitute for authentication or customer authorization.
Annotations communicate behavior, but are not a security boundary. See the MCP guidance on tool annotations.