AI Integration

MCP Server

Connect any MCP-compatible AI agent or tool to the Homerunner API using the Model Context Protocol over HTTP. The server exposes your shipments, tracking, products, and returns as callable tools.

Endpoint

The MCP server speaks the Streamable HTTP transport (JSON mode). Point your client at the POST endpoint:

POST https://mcp.homerunner.com

SSE streaming is not supported. The server returns a single JSON response per request (enableJsonResponse: true).

Authentication

There are two ways to authenticate, depending on whether your client can open a browser. Both use your Homerunner email address and integration token (from Settings → Integrations) — the same credentials you use for the REST API.

Programmatic clients (no browser)

If you connect the server from code — Anthropic's Messages API MCP connector, OpenAI's Responses API, or any custom client — there is no OAuth flow to complete. Send your credentials directly as the bearer token: the base64 of email:integration-token.

Authorization: Bearer <base64("email:integration-token")>

This is the value you pass as the connector's authorization token (e.g. authorization_token on the Anthropic connector, or the MCP tool's Authorization header on OpenAI). It is exactly the email:integration-token pair, base64-encoded — the same shape as REST Basic auth, but sent as a Bearer token rather than Basic. There is no username/password exchange and no token endpoint to call: the server validates the credentials and resolves your workspace on each request. SSO-only tools work too, provided the workspace has MCP access enabled.

Interactive clients (browser)

Desktop and CLI clients that can open a browser — Claude Desktop, Claude Code, MCP Inspector — use the standard OAuth flow automatically when you supply the server URL. It follows OAuth 2.1 (which consolidates RFC 6749 / 6750 and makes PKCE mandatory) with dynamic client registration (RFC 7591):

1Client discovers endpoints from /.well-known/oauth-authorization-server.
2Client registers itself at /register (dynamic client registration).
3Client opens the authorization URL at /authorize — a form asks for your email and integration token.
4After you submit, the client is redirected back with an authorization code and exchanges it for an access token at /token.
5The client sends the access token as a Bearer token on all MCP requests.

Quick start — Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "homerunner": {
      "type": "http",
      "url": "https://mcp.homerunner.com"
    }
  }
}

Claude will prompt you to authenticate the first time.

Available tools

Required parameters are highlighted. Tools marked SSO require signing in with your Homerunner account (the OAuth flow handles this automatically).

Workspace

get_workspace read

Returns the current workspace (account) context for this MCP session.

list_workspaces read SSO

List all workspaces the current user has access to.

switch_workspace write SSO

Switch to a different workspace by account ID or name. Takes effect on the next tool call.

query

Shipments

get_tracking read

Get tracking events for a shipment by package number.

package_number

create_shipment write

Create a shipment and return the package number and price.

carrier carrier_product carrier_service weight sender receiver servicepoint_id reference order_number description comment label_format length width height

get_shipment_price read

Get the price for a shipment without creating it. Accepts the same parameters as create_shipment.

carrier carrier_product carrier_service weight sender receiver

get_shipment read

Get details of an existing shipment by package number.

package_number

list_shipments read

List recent shipments with package numbers, carriers, statuses, and prices.

carrier created_at reference order_by order_dir limit page

lookup_shipment read

Search for shipments by reference number, order number, or package number.

query

cancel_shipment destructive

Fetches shipment details and shows a confirmation UI before cancelling. Call confirm_cancel_shipment to execute.

package_number

confirm_cancel_shipment destructive

Executes the cancellation after the user confirms in the UI.

package_number

redact_shipment destructive

Prepares to permanently redact (anonymize) all personal data on a shipment. Returns awaiting_confirmation: true. Call confirm_redact_shipment to proceed — this cannot be undone.

shipment_id

confirm_redact_shipment destructive

Permanently redacts all personal data on the shipment. Only call after the user confirms the redaction from redact_shipment.

shipment_id

Returns

list_return_products read

List available return carrier products for a given origin country.

from_country

create_return write

Create a return shipment. Accepts the same parameters as create_shipment.

carrier carrier_product carrier_service weight sender receiver

Products & Servicepoints

list_products read

List available carrier products for a country pair.

from_country to_country

get_servicepoints read

Find pickup points near an address for a given carrier.

carrier zip_code country_code street limit

get_carrier_extra_services read

List the carrier add-on / extra services available for a selected carrier product. The returned carrier_key values are the valid service_codes to pass into create_shipment.

carrier cps service_codes

get_insurance_options read

List the insurance tiers available for a carrier and package weight. Pass the selected tier's id as insurance when creating a shipment.

carrier weight

Addresses

validate_address read

Validate a shipping address and get per-field validation results.

carrier_product carrier receiver

Contacts

list_contacts read

List the saved address-book contacts (saved receivers/senders) for the current workspace. Use a contact's address fields to pre-fill a shipment's receiver or sender.

Checkout SSO

list_checkouts read

List all checkout configurations for the current workspace.

list_webshops read

List all webshops connected to the current workspace. Use shop IDs when associating a shop with a checkout.

get_checkout read

Get full details of a checkout configuration including shipping methods and rules.

preview_checkout read

Show a visual preview of a checkout including all shipping methods, rules, and an interactive rule tester.

get_checkout_filters read

Returns all available filter keys for checkout rules — types, operators, and selectable options. Always call this before creating or editing rules.

get_available_shipping_products read

Returns carrier product services available for a sender country and one or more receiver countries. Call before adding a shipping method.

sender_country receiver_countries is_return

create_checkout write

Create a new checkout configuration with shipping methods and rules.

name description type shops shipping_methods

update_checkout write

Update a checkout configuration. Use delete_shipping_method to remove methods before updating.

id name description type shops shipping_methods

attach_webshops write

Attach one or more webshops to a checkout. Additive — existing attachments are preserved.

checkout_id webshop_ids

duplicate_checkout write

Create a copy of an existing checkout configuration.

delete_shipping_method destructive

Remove a specific shipping method from a checkout. Use get_checkout to find method IDs first.

checkout_id shipping_method_id

delete_checkout destructive

Fetches checkout details before deletion and returns awaiting_confirmation: true. Call confirm_delete_checkout to proceed.

confirm_delete_checkout destructive

Permanently deletes a checkout configuration. Only call after showing the user the details from delete_checkout.

Tickets

get_ticket_types read

List available support ticket types and required attributes for a shipment. Call before create_ticket.

package_number

create_ticket write

Create a support ticket linked to a shipment. Use store_ticket_file first for file attachments.

package_number type_id from_name message attributes

store_ticket_file write

Upload a base64-encoded file attachment (PDF, JPEG, PNG). Returns a UUID to use as an attribute value in create_ticket.

base64_file

list_tickets read

List support tickets for the current workspace with their package numbers, subjects, statuses, and creation dates. Supports filtering, sorting, and pagination.

package_number reference created_at order_by order_dir page limit

get_shipment_ticket read

Get the support ticket — including its conversation thread — linked to a shipment by package number. A shipment has at most one ticket.

package_number

get_ticket_by_id read

Get a single support ticket — including its conversation thread — by its ticket ID. Returns the same shape as get_shipment_ticket.

ticket_id

post_ticket_message write

Append a reply message to an existing ticket's conversation. Optionally attach files inline as { filename, base64_file } — they are uploaded automatically (images, PDF, DOCX, XLSX, CSV, TXT; max 10 MB each, up to 10).

conversation_id from_name message files

attach_ticket_file write

Attach a single file to a ticket conversation in one step — pass the conversation_id and the file as { filename, base64_file }; it is uploaded and posted as a short message (images, PDF, DOCX, XLSX, CSV, TXT; max 10 MB).

conversation_id file

Homerunner Data

data__query read

Run a read-only SQL query against the Homerunner data warehouse. Only SELECT and WITH statements are allowed. Results are capped at 1000 rows.

sql max_rows

data__list_tables read

List all tables and views in the connected Homerunner data warehouse schema.

data__describe_table read

Describe the columns of a Homerunner data warehouse table or view.

table

Survey data (ESS)

These tools query the European Social Survey — weighted, respondent-level microdata. See the Survey Data guide for what the data contains, query semantics, and worked examples.

survey__list_datasets read

List the survey datasets, editions, and rounds available. Call first to discover valid dataset/edition values.

survey__lookup_variable read

Search survey variables by name or label text and return their label, value labels, and missing-value codes. Use to find the variable name for survey__query and to decode coded values.

q dataset limit

survey__query read

Subset and aggregate survey microdata (weighted mean/count/share, optionally grouped) or return bounded raw rows. Survey weighting and missing-value exclusion are applied by construction.

dataset edition filter aggregate select weight

homerunner__read__skill read

Load a skill reference file (Snowflake schema docs, checkout patterns, ticket types). Call before answering data or configuration questions.

filename

Updated 25 July 2026 at 10:50