Skip to content
alfe.aiDocs

Agent-led bootstrap

Agents can onboard themselves onto Alfe entirely over MCP. There are three entry paths, all starting from a connection to https://mcp.alfe.ai/mcp.

Before you start

Section titled “Before you start”

Connect an MCP client to the endpoint and, optionally, orient the agent:

  1. alfe_describe_platform — what Alfe offers.
  2. alfe_check_requirements — prerequisites and the onboarding flow.

Then pick one of the paths below.

Path 1 — Bootstrap a brand-new agent

Section titled “Path 1 — Bootstrap a brand-new agent”

alfe_bootstrap_agent registers a new agent and creates an organization for it. It’s a two-step, proof-of-work-gated flow that keeps automated sign-up abuse in check.

  1. Request a challenge. Call alfe_bootstrap_agent with an agentName (and optionally a contactEmail and a list of requestedIntegrations). The server responds with a session id and a proof-of-work challenge (a prefix and a difficulty).
  2. Solve it. Find a nonce whose hash of prefix + nonce meets the required difficulty.
  3. Submit the solution. Call alfe_bootstrap_agent again with the same agentName and a challengeResponse containing the session id and your nonce.

On success the server creates the organization and the agent, and returns:

  • tenantId and agentId.
  • An API key the agent uses from then on. Store it now, because it’s returned once.
  • A claim URL a person can open within 7 days (claimExpiresAt) to authorize OAuth integrations and add a payment method.
  • hasPaymentMethod, which says whether the organization has one yet.
  • Setup instructions in setupInstructions.

The MCP session is normally authenticated right after a successful bootstrap, so the agent can go on to call the authenticated tools. If it isn’t, call alfe_authenticate with the new key.

Call alfe_check_onboarding_status with the session id to check where a bootstrap or join has got to, and alfe_get_setup_instructions for setup steps afterward.

Path 2 — Join an existing organization

Section titled “Path 2 — Join an existing organization”

If someone has generated an invite token for you, joining takes two calls:

  1. Get a ticket. Call alfe_join_organization with the inviteToken and an agentName. The server returns a joinTicket.
  2. Join. Call it again with the same values and the joinTicket. The agent is created inside the token’s organization, with the scopes the token grants, and you receive an agentId and an API key.

Keep the ticket. If a join fails partway, presenting the same ticket resumes it instead of using up a second seat on the invite.

An agent with an admin key creates invite tokens with alfe_create_invite and lists them with alfe_list_invites. An invite takes a label and, optionally:

  • scopes — defaults to gateway:connect and agent:read. An invite can never grant admin.
  • expiresInHours — defaults to 24, up to 168.
  • maxUses — defaults to 1, up to 100.

Path 3 — Authenticate an existing agent

Section titled “Path 3 — Authenticate an existing agent”

If the agent already has an API key, call alfe_authenticate with the apiKey to authenticate the current MCP session. The server confirms the identity and scopes, and the full authenticated toolset becomes available.

After onboarding

Section titled “After onboarding”

Once authenticated over MCP, an agent can manage itself: install integrations, manage its tokens, browse templates, and set up webhooks. Tools that act across the organization need a key with the admin scope, and a bootstrap key doesn’t have it. See What a key can do.

For programmatic use outside MCP, agents can also call the Agent API directly with their API key.