Agent Cross-App Calling

An agent can call your apps' APIs for you: read an app's data, see what endpoints it has, or move data between apps, with no code. Three agents can do it, and they follow different rules:

From your coding agentCopy Anchor Link

With your agent connected to Stardeck, ask it in plain words:

• "Which of our apps can you operate?" (list_org_apps)
• "What can I call on the invoicing app?" (discover_cross_app_endpoints)
• "Get the latest orders from the storefront app" (call_cross_app_endpoint)
• "Get all customers from the CRM app and create matching contacts in the support app."

call_cross_app_endpoint calls production unless the agent asks for sandbox or branch_preview. A call that changes data shows you a preview first and runs only after you confirm. A sandbox doesn't take writes from an MCP client: it runs your app's code as you edit it, so there's no deployed version for your confirmation to cover, and it can share your live app's data. Reads still work there. To write, deploy a branch preview and call branch_preview, or call production; both ask you first. The preview names where the call really goes (the environment and address the app's routing sends it to, and the version that's live there) and the permissions it carries. Your confirmation covers exactly that: if the app is deployed again, routed elsewhere, or your permissions in it grow before the call is sent, nothing is sent and you're asked again. A connection with read-only access can make GET calls only. Cross-app calls need the agent:cross-app:call permission on the connection's role. See Tools & Permissions.

From StarcatCopy Anchor Link

When you chat with Starcat, including in the sidebar next to an app, it can call your apps the same way:

• "Get the latest orders from the POS app"
• Viewing the orders app: "Mark order #1043 as refunded."

When you're viewing an app, Starcat calls the environment you're looking at: production if you're viewing production, the preview if you're viewing a preview. Otherwise it calls production. To change that, say so: "try this against the sandbox".

Whose permissions applyCopy Anchor Link

When your coding agent or Starcat calls an app for you, the call carries your own permissions in that app: the same role and permissions you get when you sign in to it, from your app role or what your organization role was granted there. The app checks them like it checks you, so the agent can do what you could do there and nothing more. If you can't refund an order in the POS app, neither can an agent working for you; it tells you which permission you'd need instead.

• The admin APIs of apps Stardeck creates check these permissions, and your location, on every agent call. A call with nobody's permissions behind it is refused.
• In your own API routes, read them with getCrossAppCaller(request).principal from @stardeck-customer-apps/cross-app/server and check them as you check a signed-in session.
• Stardeck's own agent account never brings administrator permissions to a call; it has to act for a person.

From Starcat DeveloperCopy Anchor Link

In an app's Build tab, Starcat Developer can call other apps to test an integration you're building:

• "Call the inventory app's /api/products endpoint"
• "Call the CRM app's sandbox to test the new endpoint"

It calls as the app you're working in, with that app's deployment credentials, so it follows the same permission rules as your app's code. It also needs the calling environment checked under Developer-agent callable environments in that app's Cross-App settings.

Allow agents to operate an appCopy Anchor Link

By default, no agent can operate an app. Open the app's Settings → Cross-App tab and turn on Allow agent access. Your coding agent can turn it on with update_cross_app_settings, after you confirm.

Then choose which of the app's environments agents may call:

Narrow this set to keep agents away from environments you don't want them touching. For example, allow Preview and Sandbox only while you're still checking what the agent does.

Endpoint discoveryCopy Anchor Link

Before making a call, an agent can list what endpoints a target app exposes, and what each one expects and returns:

• "What endpoints does the project-management app have?"
• "What does the /api/tasks endpoint expect as input?"

The list comes from the deployment the agent's calls would reach: Stardeck reads each API route's methods and its route.schema.json documentation from the app's code every time it deploys, so a removed endpoint or method disappears with the deploy that removed it. An app last deployed before this was in place lists what its default branch's last scan found until its next deploy.

What still appliesCopy Anchor Link

Agent calls go through the same checks as app calls. The agent can't bypass them:

• The endpoint must be published, or the app must have Allow all endpoints on. A method the deployed route doesn't have is refused before it reaches the app.
• The app checks the permissions of the person the agent acts for.
• Rate limits apply, and every call is logged under Recent calls.
• For your coding agent and Starcat, the target app must have Allow agent access on for the requested environment.
• For Starcat Developer, the calling app needs a grant or allow-all access to the target.

If a call is refused, the agent tells you why and what to turn on.

Example: let agents read a POS appCopy Anchor Link

Add API routes so agents can check sales, look up orders, and see inventory levels. Document
each one with a route.schema.json.

To let agents change data, add write endpoints ("Add endpoints so agents can create orders and adjust inventory") that check the caller's permissions. Agents can call any published endpoint; the endpoint decides what each person may do.