Connect your tools#

Use this guide when your team already runs Porcupine. Ask its administrator for the instance URL and an invitation to your email address. An invitation grants access; you request a verification code when you sign in to each tool.

If you are setting up the instance, start with hosting and team sign-in.

Connect an agent through MCP#

Give your agent the instance URL and the agent guide. Use the instance's /mcp endpoint, for example https://analytics.example.com/mcp.

For an email-enabled instance, the connection follows these steps:

Start the client's OAuth connection to Porcupine.
Enter your invited email address on the Porcupine authorization page.
Request a verification code and enter the code from your inbox.
Select the projects and approve the permissions shown for this tool.

The administrator registers the application's callback URL once per instance. If your client asks for a client ID or secret, get its registration details from the administrator. Do not use your email verification code as a client secret. Local Codex setup and the dedicated administrator connection are described in team sign-in.

Once connected, ask your agent:

List the projects I can access. For the project I choose, discover the event names and properties, then count events by name.

The agent uses porcupine_docs to discover operations and porcupine_call to execute them. Query your events explains the workflow. The MCP reference describes tool arguments and responses.

Connect the CLI#

Install the standalone CLI for your operating system. Replace the example origin with your instance's exact URL:

export PORCUPINE_URL=https://analytics.example.com
porcupine login
porcupine list-projects

Login opens the browser for email verification and consent. The ordinary login requests read access to events and project information. An instance administrator can use porcupine login --admin for administrative work.

You should see only projects allowed by your account and the connection you approved. Copy a project ID and continue with your first query.

CLI browser login requires email sign-in on the instance. The optional upstream OIDC mode supports read-only MCP. See authentication options.

Connect a backend or shared agent#

Ask an administrator for a service key with the projects and permissions that integration needs. Service accounts belong to the instance and work independently of the person who created them.

For HTTP or the CLI, use an API-audience key. Load it into PORCUPINE_API_KEY through your secret manager. For MCP clients that accept a bearer header, use an MCP-audience key on /mcp. A key for one audience cannot be used for the other.

Change or remove access#

An administrator can disconnect one tool with revoke-oauth-grant, or revoke a person's account with revoke-human. Revoking a person disconnects all of that person's tools. Service clients and their keys are managed separately. See people and service keys.