Bicycle connector for Claude
Setup, usage, permissions, and tool reference · Last reviewed September 25, 2026
Bicycle connects Claude to the data models and analytics apps in your Bicycle workspace through the Model Context Protocol (MCP). Start with a business question, inspect the relevant metrics, and turn the results into an app your team can use.
This documentation covers the hosted connector at https://app.bicycle.ai/mcp. It is intended for people connecting Bicycle, workspace administrators reviewing its access, and developers inspecting its MCP capabilities.
What you can do
| Goal | How Bicycle helps |
|---|---|
| Understand your data | Discover available models and inspect their measures, dimensions, and metric definitions. |
| Investigate a business question | Query a model, compare periods, and break results down by available dimensions. |
| Build an analytics app | Create a draft with metrics, trends, and breakdowns; preview its data and validate it before publishing. |
| Work with existing apps | Find apps, inspect their versions and views, ask questions, and generate summaries. |
| Share recurring reports | Configure app snapshots for email delivery and manage existing schedules. |
A model defines the business metrics and dimensions you can query. An analytics app presents those results as reusable views, such as a scorecard, trend chart, or breakdown table. A schedule delivers a snapshot of an app at a specified time.
Before you begin
Have the following ready:
- A Bicycle account with access to the workspace you want to use.
- At least one configured data model for analysis, or an existing analytics app to inspect.
- The Bicycle permissions needed for your intended actions. Publishing, sharing, and scheduling can change what other people receive or access.
- A Claude account where connectors are available. For an organization account, ask its owner to make Bicycle available if necessary.
Claude and Bicycle use separate sign-ins. Authorize the connector with the Bicycle account that has access to your workspace.
Connect your account
1. Add Bicycle in Claude
If Bicycle already appears in your connector list, select it and continue to sign-in below.
Open Customize → Connectors → Add custom connector. For Team or Enterprise, an organization owner first adds the connector under Organization settings → Connectors; members then connect their own accounts. Claude's connector setup instructions
Use these settings:
| Field | Value |
|---|---|
| Name | Bicycle |
| MCP server URL | https://app.bicycle.ai/mcp |
| Connector type, if asked | Web |
| Authentication, if asked | Sign in now |
| OAuth client, if asked | Use Claude's published identity |
| Manually entered client ID or client secret | Leave empty |
| Request headers | None required |
The endpoint is the same for Bicycle workspaces hosted at app.bicycle.ai. Enter the MCP URL above, rather than a workspace login page or an individual app link.
Bicycle uses OAuth 2.0 with Client ID Metadata Documents (CIMD) and PKCE S256. Choose Claude's published identity; Dynamic Client Registration is disabled. You do not need to generate an API key or enter an OAuth client secret.
2. Sign in to Bicycle
Choose Connect. Complete the Bicycle sign-in using your existing account. If a workspace selector appears, choose the workspace you intend to use. Review the requested access and approve the connection, then return to Claude.
Enter your password only on the Bicycle sign-in page. It is not needed in a chat message or in the connector's URL.
3. Verify the connection
Enable Bicycle for the conversation through Claude's + → Connectors menu. Claude's conversation controls
Start with:
Use Bicycle to list the data models available to me. Show each model's name and ID.
Then choose a model:
Describe this model's measures and dimensions, explain its main metric definitions, and identify a date range with available data.
A successful result should identify real models from your workspace. An empty list can mean the workspace has no configured models or that your account needs additional access.
Explore your business data
Begin with discovery so that Claude can use the model's actual metric and dimension names. Specify the metric, dates, comparison, and breakdown you want.
For example:
Using the model we just inspected, show the daily trend for its main conversion metric over the last complete week. Include the underlying counts and break the result down by device platform if that dimension is available.
Follow up with:
Compare that period with the previous complete week. Explain the largest changes and show the numbers supporting each observation.
For reproducible results, ask Claude to state the model, metric definition, filters, time zone, and date boundaries it used. The requested period must overlap the model's available data. A missing result and a measured value of zero are different outcomes.
Query behavior and limits
Queries use Bicycle's semantic models and their declared metric definitions. Available fields and breakdowns depend on the selected model. Discover metric columns and supported dimensions before requesting a detailed analysis.
- Queries require a bounded time range. The standard range uses an inclusive start and an exclusive end:
from <= timestamp < to. query_rundefaults to cached data. A cache miss or unsupported breakdown requires investigation; it does not establish that the business metric is zero.- Semantic SQL supports model queries, filters, time grouping, sorting, and limits. It does not support arbitrary joins or subqueries.
- Results may be truncated.
query_rundisplays at most 200 rows per response; inspect the returned row count and truncation information before treating a table as complete. query_compilechecks how a query translates, andquery_explaininspects its routing without running the data query.
Build and publish an analytics app
Use a draft to review the app's layout and queries before making a version available to viewers.
Create a draft scorecard from this model with three headline metrics, a daily trend, and a breakdown by an available dimension. Preview the data, validate the draft, and show me the app link and any validation issues.
Review the metric definitions, date filters, number formats, and returned data. You can request changes in the same conversation:
Add a comparison with the previous period and explain how each displayed metric is calculated. Keep this version as a draft while I review it.
When satisfied, ask Claude to publish the specific app and version. Review any requested tool approval before proceeding.
A draft and a published app are different states. If an app link reports that there is no published version, ask for the latest draft to be validated and published. After changing an existing app, confirm which version is published before sharing its link.
Publishing grants read access across the Bicycle workspace. Treat publication as making that version available to the workspace, not just to its creator. Additional sharing grants can give a user or other supported principal read, write, publish, or admin access; changing these grants requires app administration permission.
| App or version state | Meaning |
|---|---|
| Draft | A version under preparation; an unpublished version is private to its creator. |
| Validated | The version passed validation and is eligible for publication. It is not live yet. |
| Published | The app's current live version, readable across its workspace. |
| Superseded | A previously published version replaced by a newer publication. |
| Unpublished app | The app has been taken offline. Its versions are retained. |
The latest draft and the current published version can differ. Ask Claude to show both before revising or publishing an existing app.
Ask questions about an existing app
Find the app first, then use its name or ID in follow-up requests:
List my published Bicycle apps. For the app I choose, summarize its views, metrics, filters, and current date range.
Explain how this app calculates its primary metric and suggest two useful follow-up analyses.
Include the app link or ID when several apps have similar names. If you are reviewing a particular version, state that version explicitly.
App questions and summaries operate on published apps with app chat available. A question can create an app chat thread; summaries may be served from cache. These operations do not revise the app's definition.
Set up recurring email snapshots
A snapshot captures an app view for delivery. Before creating a schedule, choose the published app, view or saved link, reporting period, time zone, delivery time, format, and recipients.
Start with a preview:
Prepare a weekly snapshot of this published app for Monday at 9:00 AM in my chosen time zone. Show the reporting period, view, recipients, and format. Test the snapshot with deliver=false so no email is sent.
Once you have reviewed the preview, provide the recipient addresses and ask Claude to create or enable the schedule.
| Setting | What to specify |
|---|---|
| App and view | The app plus an existing saved link_id, an app-view URL, or view settings. |
| Timing | A cron expression and time zone; ask Claude to restate the resulting delivery times in plain language. |
| Reporting period | Explicit YYYY-MM-DD dates, or one of 7d, 30d, 90d, quarter, or ytd when that preset is offered by the app's time control. |
| Recipients | The email addresses that should receive the snapshot. |
| Format | PNG, PDF, or both. |
| Tabs | The saved/default tab, selected tab IDs, or all tabs supported by the app. |
| Email content | Optional subject, body, and summary placement. |
Creating a schedule addressed only to yourself requires read access to the app. Including other recipients requires write access. Changes to existing schedules depend on their ownership, recipients, and your app and connector permissions.
dataapp_schedule_test defaults to deliver=false. Setting deliver=true sends a real test email. Running an existing schedule is also a real delivery action. If a test reports that it is still in progress, check its run status before starting another delivery.
To review or stop deliveries:
List this app's schedules with their timing, time zones, recipients, and enabled status.
Disable the weekly schedule we just created and confirm its final status.
Schedules are stored in Bicycle. Ending the Claude conversation or disconnecting the connector does not itself disable a Bicycle schedule. Disable unwanted schedules separately.
If an update reports a conflict, list the schedules again, review the latest settings, and retry against the current updated_at value. This avoids overwriting another person's changes.
Permissions and data use
The connector supports both reading and writing. Reading includes inspecting models, running queries, and listing apps or schedules. Writing includes creating app versions, publishing or unpublishing apps, changing sharing, and managing schedules.
When Claude calls Bicycle, it sends the parameters needed for the operation, such as a model ID, query, app configuration, or schedule settings. Bicycle returns the resulting data or operation status to Claude. Scheduled delivery also sends the configured snapshot to its email recipients.
Claude's tool approvals and Bicycle's account permissions are separate controls. An approval in Claude does not grant an app permission that your Bicycle account lacks. Check the action's target app, version, audience, and recipients when reviewing a request.
| Action | Persistent effect to consider |
|---|---|
| Create or revise an app | Saves an app or a new draft version. |
| Publish | Changes the current live version and grants workspace-wide read access. |
| Unpublish | Takes the app offline while retaining its versions. |
| Share | Changes a principal's app permission. |
| Save a model profile | Saves reviewed metric and dimension bindings used for subsequent app design in the workspace. |
| Upload an app file | Stores content under a blob name declared by the app. |
| Ask an app or request a summary | May create a chat thread or cached summary. |
| Create or change a schedule | Saves delivery settings that remain in Bicycle independently of the chat. |
| Run a schedule or deliver a test | Sends a snapshot to the configured recipients. |
Use an account and workspace appropriate for the data you intend to work with. Review recipients and sharing changes carefully, and follow your organization's rules for using business data with Claude. Bicycle's handling of personal information is described in its Privacy Policy.
Tool reference
You can use the connector through natural-language prompts; tool names are included here to help identify approval requests and diagnose issues. The connected server provides the exact parameter schemas. This reference covers the 39 tools in the version reviewed on the date above.
Models and queries
These tools inspect the model catalog or read data; they do not change app definitions.
| Tool | Purpose |
|---|---|
query_list_models | List available semantic models. |
query_describe_model | Inspect metric columns, event types, dimensions, and availability. |
query_describe_metric | Explain one metric, including its expression, ratio components, and supported breakdowns. |
query_search_fields | Find exact metric and field names. |
query_dimension_values | Discover dimension values and counts for filters. |
query_compile | Compile semantic SQL and report issues without executing the data query. |
query_explain | Explain query routing and cacheability without executing the data query. |
query_run | Run a bounded semantic query and return a result table. |
App design
| Tool | Purpose and effect |
|---|---|
design_model_card | Read candidate measures, dimensions, display formats, and the model's data window. |
design_profile_get | Read the workspace's saved design bindings for a model. |
design_profile_save | Save reviewed model bindings for future app design. |
design_recipes | Browse available analysis panels and their data requirements. |
design_templates | Browse app layouts and their panel slots. |
design_spec_validate | Validate an app specification and resolve model-backed display information. |
design_recipe_preview | Preview an analysis panel using cached rows and show its queries. |
design_compose | Build and validate an app or draft version from a specification; publication is a separate step. |
design_spec | Read the specification used to build a composed app version. |
design_spec_diff | Compare the specifications of two app versions. |
design_brief | Create a separate executive-brief app from an existing composed app. |
design_blob_upload | Upload content to a file slot declared by the app. |
design_blob_list | List declared app files and their upload status. |
design_store_describe | Inspect an app's declared cache and file storage. |
App management, questions, and schedules
| Tool | Purpose and effect |
|---|---|
dataapp_list | List accessible apps. |
dataapp_describe | Inspect an app's state, versions, validation results, and URL. |
dataapp_versions | List visible app versions, including the caller's private drafts. |
dataapp_url | Return the hosted app URL. |
dataapp_download_url | Generate a temporary download URL for a version's bundle. |
dataapp_start | Create an app and return its initial bundle-upload steps. |
dataapp_new_version | Start a new draft version for a bundle upload. |
dataapp_upload_url | Renew upload steps for a version awaiting its bundle. |
dataapp_complete_upload | Verify the uploaded bundle and validate its manifest and queries. |
dataapp_publish | Make a validated version current and readable across the workspace. |
dataapp_unpublish | Take an app offline while keeping its versions. |
dataapp_share | Grant app permissions to a supported principal. |
dataapp_ask | Ask a published app a question and return its answer and any reported query details. |
dataapp_summary | Summarize a published app's current screen. |
dataapp_schedule_list | Read schedules, recipients, timing, owner, and update information. |
dataapp_schedule | Create, update, enable, disable, delete, or run a schedule. Running it triggers delivery. |
dataapp_schedule_test | Rehearse snapshot generation; send a test email only when delivery is requested. |
dataapp_schedule_list is the schedule-reading tool. The separate dataapp_schedule tool changes schedules or runs a delivery. A preview without email may still create a test run and generated snapshot artifacts.
MCP prompt and resources
For MCP clients that expose prompts and resources, the connector also provides:
| Type | Name or URI | Purpose |
|---|---|---|
| Prompt | design-data-app | Guided app design using the Ask, Show, Ship workflow. |
| Resource | studio://skill/ask-show-ship | The app-design workflow. |
| Resource | studio://skill/semantic-query | Semantic query syntax and guidance. |
| Resource | studio://recipes | Analysis recipe catalog. |
| Resource | studio://templates | App template catalog. |
Client interfaces differ in how they display these capabilities. The examples in this guide can be requested directly in conversation.
Troubleshooting
| What you see | What to check |
|---|---|
| Bicycle is unavailable in Claude | Check the connector list. On an organization account, ask an owner whether Bicycle has been added and made available. |
| Sign-in fails or the connection expires | Confirm you can sign in to Bicycle directly, then reconnect from Claude. Verify the server URL and published-identity setting. |
| The wrong models or apps appear | Check the Bicycle account and workspace used during sign-in. Reconnect with the intended account if needed. |
| No models are listed | Ask your Bicycle workspace administrator to check your membership and whether models have been configured. |
| A query returns no rows | Check the model's available dates, filters, and time zone. Start with a smaller query and fewer filters. |
| A query reports a cache miss or unsupported breakdown | Inspect the metric's available dimensions and dates with the model and metric tools. Adjust the request to available data; do not treat the error as zero activity. |
| A draft fails validation | Ask Claude to show the validation details and correct the affected query or configuration before publishing. |
| An app has no published version | Validate the latest draft, then publish the intended version. |
| An action is denied | Ask your Bicycle administrator to check the permissions needed for that action. |
| A schedule preview produces no email | A test with deliver=false intentionally sends no email. Review the preview before requesting a real delivery. |
| Scheduled email arrives at an unexpected time | Check the schedule's enabled status, time zone, reporting period, recipients, and next run time. |
A schedule update reports 409 conflict | Read the schedules again and use the latest updated_at after reviewing the current settings. |
| A test returns "still in progress" | Check the returned run reference before starting another test, especially if email delivery was enabled. |
Disconnect Bicycle
Turn Bicycle off for a conversation in its connector controls. To remove the connection, open Customize → Connectors and use Bicycle's removal control; organization owners manage organization connectors in their admin settings. Manage connectors in Claude
Removing a connector does not delete apps or schedules already created in Bicycle. Review those separately if you also want to stop deliveries or take an app offline.
Get help
Contact support@bicycle.ai for Bicycle connection, model, app, or scheduling issues. Include the workspace name, affected model or app ID, approximate time and time zone, and the visible error message. Omit passwords, access tokens, and sensitive query results.
For Claude account or organization settings, consult Claude's connector documentation or your Claude organization owner.