> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agent-loadout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Agent Loadout from a Vercel App with Vercel Connect

> Let Vercel Connect hold the OAuth grant and hand your deployment short-lived Agent Loadout tokens for the MCP server or the REST API, with no agent token in your environment variables.

An app or agent on Vercel usually reaches Agent Loadout with an agent token stored as an environment variable. [Vercel Connect](https://vercel.com/docs/connect) removes that secret: it keeps the OAuth grant on Vercel's side, and your code asks for a one-hour access token whenever it needs one. Each grant is bound to one agent and to the permissions someone approved on the Agent Loadout consent screen.

## What you need

* A Vercel project linked to your local directory with `vercel link`
* An Agent Loadout organization in which you are an owner or admin, because only they can approve a connection
* The agent your app should act as

## How the connection works

1. Vercel Connect reads the discovery document at `https://agent-loadout.com/.well-known/oauth-authorization-server` and registers itself as an OAuth client. Agent Loadout does not issue client secrets, so you have nothing to copy.
2. The first token request for a user sends that person to the Agent Loadout consent screen. They sign in, choose the organization and the agent, and tick the permissions. This creates an agent token that appears on the agent's **Tokens** tab under the connector's name.
3. From then on, Vercel Connect refreshes the grant in the background. Access tokens last one hour. Refresh tokens rotate on every use and expire after 90 days without use.

The same access token works with the MCP server at `https://agent-loadout.com/api/mcp` and with the REST API at `https://agent-loadout.com/api/v1`.

## Set up the connector

<Steps>
  ### Create the connector

  ```bash theme={null}
  vercel connect create agent-loadout.com --name agent-loadout
  ```

  When Vercel asks for scopes, pick the permissions your app needs, for example `email:read email:send`. The scopes are listed in [Authentication](/api-reference/authentication#oauth-scopes). If you request none, the consent screen offers `email:read` and `email:send`.

  ### Attach it to your project

  Look up the connector's UID with `vercel connect list`. Then attach the connector to the linked project and pull a development OIDC token:

  ```bash theme={null}
  vercel connect attach <CONNECTOR_UID>
  vercel env pull
  ```

  ### Approve access and test a token

  ```bash theme={null}
  TOKEN=$(vercel connect token <CONNECTOR_UID> --yes)
  curl https://agent-loadout.com/api/v1/me -H "Authorization: Bearer $TOKEN"
  ```

  The first run opens the consent screen in your browser. The response names the agent and the capabilities you approved.

  ### Install the SDK

  ```bash theme={null}
  npm install @vercel/connect
  ```
</Steps>

## Call the REST API

`getToken` returns a current access token for one subject. Use a stable ID from your app's own session as the subject.

```ts app/lib/agent-loadout.ts theme={null}
import { getToken } from '@vercel/connect';

export async function listInboxes(userId: string) {
  const token = await getToken('<CONNECTOR_UID>', {
    subject: { type: 'user', id: userId },
  });

  const response = await fetch('https://agent-loadout.com/api/v1/inboxes', {
    headers: { Authorization: `Bearer ${token}` },
  });
  return response.json();
}
```

If that user has not approved access yet, `getToken` throws `UserAuthorizationRequiredError`. Show a "connect your account" button in that case.

## Use the MCP server with the AI SDK

`connectAuthProvider` asks Vercel Connect for a token before each MCP request:

```ts app/api/chat/route.ts theme={null}
import { createMCPClient } from '@ai-sdk/mcp';
import { connectAuthProvider, ConsentRequiredError } from '@vercel/connect/ai-sdk';

export async function POST(request: Request) {
  const userId = 'user_123'; // Take this from your authenticated session.
  try {
    const mcpClient = await createMCPClient({
      transport: {
        type: 'http',
        url: 'https://agent-loadout.com/api/mcp',
        authProvider: connectAuthProvider(
          '<CONNECTOR_UID>',
          { subject: { type: 'user', id: userId } },
          { redirectUrl: new URL('/', request.url).toString() },
        ),
      },
    });
    const tools = await mcpClient.tools();
    // In a chat route, pass `tools` to streamText and close the client when the turn ends.
    await mcpClient.close();
    return Response.json({ tools: Object.keys(tools) });
  } catch (error) {
    if (error instanceof ConsentRequiredError) return Response.redirect(error.url, 303);
    throw error;
  }
}
```

The [Vercel guide for the AI SDK and MCP](https://vercel.com/docs/connect/frameworks/ai-sdk-and-mcp) covers streaming and tool approval in full. Add tool approval for tools that send mail, spend money or run commands.

## Permissions

Each token carries every permission approved for that grant. Agent Loadout does not narrow a token below its grant, so if parts of your app need different permissions, create a connector for each part.

When a tool or endpoint needs a permission the grant lacks, the request fails with a permission error. Approve the connection again with the extra scope.

## Disconnect

Revoke the token on the agent's **Tokens** tab, or revoke the grant in Vercel with the dashboard, the CLI or the SDK's `revokeToken`. Vercel Connect calls the Agent Loadout revocation endpoint, so the agent token stops working immediately. Deleting the connector revokes its tokens as well.

## Troubleshooting

<Accordion title="The token request fails with invalid_target">
  Agent Loadout issues tokens only for `https://agent-loadout.com/api/mcp` and `https://agent-loadout.com/api/v1`. Remove any other value from the `resources` option.
</Accordion>

<Accordion title="The consent screen rejects my account">
  Only owners and admins of an organization can connect its agents. Ask an owner to approve the connection or to change your role.
</Accordion>

<Accordion title="getToken throws NoValidTokenError">
  The grant has been revoked, or its refresh token went unused for 90 days. Approve the connection again.
</Accordion>