MCP Integration
Connect your AI assistant to GetButters with OAuth or a private API key to work with projects, events, and KPI cards.
Connect your AI assistant to GetButters to find projects, read events, record events, and update KPI cards. Use the remote MCP server at https://app.getbutters.com/mcp with Streamable HTTP.
Connect with your GetButters account
- Open your assistant's MCP or remote-server settings.
- Add
https://app.getbutters.com/mcpas the server URL. - When prompted, sign in to GetButters.
- Choose your organization and approve the connection.
- Ask the assistant to list your projects to check the connection.
Every tool works within the organization you selected. Removing your organization membership or revoking the connection prevents further access. If your client requests scopes, include mcp; offline_access lets it refresh the connection without asking you to sign in each time.
Connect with a private API key
Open API Keys in the app at /app/api and create a private API key. In your MCP client's server configuration, use the same server URL and send the key in the Authorization header.
{
"mcpServers": {
"getbutters": {
"url": "https://app.getbutters.com/mcp",
"headers": {
"Authorization": "Bearer ev_YOUR_PRIVATE_API_KEY"
}
}
}
} Your client's configuration format may differ. Replace the example with your private key and store it in the client's secret settings when available. Existing private ev_ keys work; browser publishable pk_ keys cannot connect to MCP. Revoking a private key on API Keys disables its MCP access.
What your assistant can do
list_projects: find projects and their IDs in your organization.create_project: create a project within your plan's project limit.list_events: read events with category and search filters. Request up to 100 events per page and pass the returnednextCursorascursorfor the next page.send_event: record an event, optionally identifying a person. Events count toward your plan's allowance. Notifications are off by default; setnotify: trueonly when you want configured destinations alerted. If you supplycreated_at, use a Unix timestamp in seconds.set_insight: create or update a KPI card by title within a project.get_charts: read daily event counts grouped by category.
Start with list_projects, then use a returned project ID as project in the other tools. For a read-only connection check, ask the assistant to list recent events from a project. Creating projects and sending events can create duplicates if a successful request is repeated.
Troubleshooting
Invalid or revoked API key
Check that you supplied a current private ev_ key in Authorization: Bearer .... Replace a revoked key with a new one from API Keys. A publishable pk_ key is not accepted.
Connection revoked or membership no longer valid
Reconnect with OAuth and select an organization you still belong to. A revoked connection or removed membership cannot access that organization's data.
Invalid origin
Browser requests must come from the GetButters app's configured origin. Use your client's remote MCP connection rather than a request from an unrelated web page. Native clients generally omit the Origin header.
A project or event request fails
Use list_projects to check the project ID, confirm that you selected the correct organization, and check your plan's project and event allowances. MCP uses the same validation and limits as the REST API.
See the API Reference and People and identify for related guidance.