start here

start using Vercel with your agents

sign up, open a project, and authorise Vercel from its connectors settings.

Start 7-day trial with Vercel
integrationsconnectorupdated
schematic diagram of the work aldena agents do through Vercel
Vercel

ai agent for vercel: start a run when a deployment fails

connect vercel to an aldena project and its agents wake on deployment, project and domain events, with the branch, the commit message and the error in hand.

events
7
resource types
2
access grants
2

a failed deployment is a log file and a guess, and the moment it fails is when an agent should start. connecting vercel to an aldena project turns deployment, project and domain events into runs: an agent creates an event routine on a vercel project or the whole team from a chat, and the next matching event starts a run with the branch and commit in hand, in that chat or in a new chat in the same project when the routine opens one per event. because each conversation in the aldena project gets its own sandbox, the agent can reproduce the build there. reading logs and acting on deployments goes through vercel's own mcp server.

subscribing from a chat

vercel_subscribe takes a resource, the events to watch, and what the agent should do when one arrives. a routine on a vercel project takes its id or name such as acme-web, resolved at subscribe time so a later rename does not break it, and fires when a deployment is created, succeeds, errors or is canceled. a team-wide routine fires on the deployments of every vercel project in the team, and also when a project is created or removed and when a domain is added. either one takes an optional environment, production or preview. vercel_unsubscribe takes an event routine off again, and the aldena project's Settings → Routines lists every routine the agents hold.

each notification carries the event routine, the actor, a one-line summary and a link. a deployment event also carries the git branch and the commit message when vercel sends them, plus the error message on a deployment error. that text is fenced off as untrusted data and capped at 4,000 characters, so a commit message can inform the agent but cannot instruct it.

grant all vercel projects, one team per aldena project

when you approve the integration, vercel asks which of its projects it may reach. grant all projects so team-wide events arrive: an installation limited to selected projects never receives project created or removed events. a vercel team can be connected in one aldena project at a time, and vercel only reveals the team after you approve, so connecting a team another aldena project already holds fails at the end.

going beyond triggers with vercel's mcp server

for reading deployments and runtime logs and managing vercel projects, add vercel's mcp server to the same aldena project. it acts as the person who signs in to it.

  1. open the project's Settings → Connectors, and under MCP servers press Marketplace.
  2. install Vercel. it installs as vercel-mcp, so it does not clash with the connector.
  3. open the sign-in link it gives you and approve access in the browser.

once it is connected, agents reach its tools through mcp_search and mcp_call, each tool gets its own row in the project's permissions, and every action runs as the person who signed in, not as aldena. the mcp servers page covers the rest.

example tasks

  • 01

    watch production and tell me the moment a deployment errors.

    an event routine on the vercel project, filtered to production, starts a run in this chat on each error with the branch, commit message and error in the notification, and the agent reports it here.

    vercel_subscribe
  • 02

    when a preview build fails, work out why and push a fix.

    each failed preview starts a run. the agent reads the build log through vercel's mcp server, reproduces the build in the conversation's sandbox, and pushes the fix to the same branch.

    vercel_subscribemcp_callgithub_git_syncbashgithub_git_push
  • 03

    stop watching the marketing site.

    the agent lists its routines, finds the event routine on that vercel project, and removes it, so its deployments no longer start runs.

    list_routinesvercel_unsubscribe

what it will not do

the connector does not read build logs, deploy, roll back, or change environment variables, domains or project settings. it reaches one vercel team, the one the aldena project connected, and no event starts a run while the connection waits for a reconnect.

what starts a run

every Vercel event an agent can subscribe to, grouped by resource. an agent subscribes from a chat with vercel_subscribe, and each matching event starts a run in that chat, or in a new chat in the same project when the routine opens one per event.

project4 events
  • deployment.created
  • deployment.succeeded
  • deployment.error
  • deployment.canceled
team7 events
  • deployment.created
  • deployment.succeeded
  • deployment.error
  • deployment.canceled
  • project.created
  • project.removed
  • domain.created

what you grant

aldena's Vercel app is configured for this access, and Vercel shows it on its own consent screen. every project gets the same set, and there is nothing to pick.

  • Projects (read)

    Check the projects agents subscribe to.

  • Deployments (read)

    Receive deployment events for the team's projects.

how to connect Vercel

connecting Vercel takes one authorisation round trip, started from inside the project that needs it.

  1. open the project's connectors settings

    connections belong to a project, not to your account or the team. open the project that needs Vercel, go to settings → connectors, and press connect. other projects stay untouched.

  2. authorise with a real account

    any member of the project can start the connection, and they authorise as themselves. Vercel asks only for the fixed access listed above, with no scopes to choose.

  3. an agent subscribes from a chat

    ask an agent in a project chat to watch something in Vercel. it calls vercel_subscribe with the resource, events and intent, and settings → routines lists each routine it holds.

  4. a matching event starts a run

    each matching event starts a run with the event and its content in hand, in the chat where the agent subscribed or in a new chat in the same project when the routine opens one per event. disconnecting Vercel stops every subscription to it.

data handling and security

a connector holds one credential and turns Vercel events into runs. the credential stays inside the project that connected it, and event text is data, never instructions.

  • one connection, one project

    the Vercel credential is stored against the project it was authorised in. no agent in another project can use it, and there is no team-wide connection to inherit by accident.

  • tokens encrypted at rest

    the Vercel token is encrypted before it is stored, and it never appears in a chat or in an agent's prompt. agents get the events, not the credential.

  • events only where a routine watches

    aldena verifies each delivery came from Vercel. an event starts a run only for a routine it matches, in the chat that set the routine up or in a new chat in the same project when the routine opens one per event. nothing starts while the connection needs a reconnect.

  • event content is untrusted

    event text may come from a stranger. it reaches the agent as fenced data capped at 4,000 characters, and the agent is told never to follow instructions in it.

  • revocation is one click

    disconnect Vercel and the project's event routines on it stop at once, along with the stored credential.

the permissions tab in project settings with reads on allow, edits on ask, and write file and bash on deny

each Vercel tool agents hold has its own allow, ask or deny row in the project's permissions. see human in the loop for approvals and isolated projects for isolation.

faq

how does an agent know a vercel deployment failed?

vercel_subscribe attaches it to a project or the connected team. deployment created, succeeded, errored and canceled events then start a run with the git branch, the commit message and, on an error, the error message in the notification. each run happens in the chat where it subscribed, or in a new chat in the same project when the routine opens one per event.

can an ai agent read my vercel build logs or redeploy?

yes, through vercel's own mcp server rather than the connector. install vercel from the aldena project's mcp marketplace with a browser sign-in, and agents read deployments and logs and act on projects through mcp_call, acting as the person who signed in. the connector itself only starts runs.

why does the agent miss project events?

project created and project removed only reach a team-wide event routine when the aldena integration was installed with access to all projects. an installation limited to selected projects never receives them, so grant all projects on vercel's consent screen if agents should hear about team-wide changes.

which vercel account does an aldena project reach?

exactly one. a vercel team can be connected in one aldena project at a time, and vercel only reveals the team after you approve, so connecting a team another aldena project already holds fails at the end. disconnecting uninstalls the integration from the team and frees it for another aldena project.

can an agent watch only production deployments?

yes. an event routine takes an optional environment, production or preview, and then only deployments to that target start a run. project and domain events carry no target, so an environment filter never matches them.

ready when you are

spin up your first project.

one project per client, product, or piece of work, staffed with intake, requirements, build and code review agents.