Connecting External Services

If an agent needs to read your GitHub repos or write to a Notion page, it needs to log in to that service on your behalf. UpServe is designed so you only do this once. After that, any skill that uses the same service will reuse the credential automatically — you don’t log in again, and the credential is forwarded to the skill at runtime.

These connections all live in one place: the Integrations sub-tab under Skills (https://upserve.app/skills/integrations ). Web, iOS, and Android all use the same layout — services are grouped by category, and clicking a card lets you connect, disconnect, and manage an organization’s designated account all from one screen.

At a glance

How to connect

There are four places to connect an external service. Any of them produces the same result — use whichever is more convenient.

Path A — Connect from the Integrations hub (fastest)

1. Go to Skills → Integrations (https://upserve.app/skills/integrations ). Services are grouped into cards by category — docs, projects, communication, and so on.
2. Click the card for the service you want to connect — a detail panel opens.
3. Click Connect in the panel to open the external service’s login screen. Review the requested permissions and approve — you return to UpServe automatically.
4. The panel now shows the connected account name. The same panel also holds organization designation (see “The account organization-shared agents use” below), which skills use this service, and any alternate connection method (MCP) for the same service.

   [1] Skills tab → Integrations sub-tab
              │
              ▼
   [2] Click a card → detail panel opens
              │
              ▼
   [3] Click "Connect" → sign in + approve permissions
        (the service's own consent screen)
              │
              ▼
   [4] Auto-redirect back to UpServe
        Panel shows the connected account name

Path B — Connect from an installed skill card

1. Go to Skills → My Library  — if you’ve already installed a skill that needs a connection (GitHub, Notion, etc.), its card shows a Connect Required prompt.
2. Click that prompt to open the same sign-in and approval screen as Path A.
3. The card now shows the connected account name.

Path C — Connect from Agent Settings

You can also connect while adding the skill directly to an agent.

1. Go to the agent page → Settings tab → open the Skill Selector.
2. Toggle the skill that needs OAuth ON.
3. An OAuth row appears below the skill card. The button state tells you where things stand:
   • Connect — not yet connected. Click to open the external service’s login screen.
   • Connecting… — redirect is in progress.
   • Reconnect — already connected or re-authentication is needed. Click to reopen the consent screen.
   • [Service] connected — active and ready.
4. Click Connect and approve the permissions on the external service’s screen. When you return, the connection row shows [Service] connected.

   [1] Agent Settings → Skill Selector
              │
              ▼
   [2] Toggle skill ON
              │
              ▼
   [3] OAuth row appears — click "Connect"
              │
              ▼
   [4] Sign in + approve permissions
              │
              ▼
   [5] Auto-redirect — row shows "[Service] connected"

Path D — Connect from a card in the chat

This is the most common path. When an agent runs into a task that needs a service it isn’t connected to yet, it shows a Connect card right in the conversation.

1. Mid-task, the agent posts a card in the chat with a Connect [Service] button.
2. Click that button to open the external service’s login screen (the same consent flow as the other paths).
3. Approve the permissions and return — the agent picks up the task where it left off.

   [1] Agent needs a service it isn't connected to
              │
              ▼
   [2] "Connect [Service]" card appears in the chat
              │
              ▼
   [3] Click the button → sign in + approve permissions
              │
              ▼
   [4] Auto-redirect — the agent resumes the task

If what the skill needs is one of the MCP servers covered under “Connecting more services” below, clicking the button behaves a little differently. If you’ve already registered that server somewhere else, a single confirmation connects it to this agent right away — no external login screen. If it isn’t registered yet, the button takes you straight to that service in the Integrations hub so you can finish registering it there. This card currently only appears in the web app — not yet on iOS or Android. On mobile, connect the service the agent named directly from the Integrations hub instead.

Marketplace skill cards and detail pages show an Integration required: [Service] badge even before you install, so you can connect ahead of time from the Integrations hub.

You only connect each service once. If a second skill that uses the same provider is toggled on later, it reuses the existing connection without a new sign-in.

Campaign-linked quickstart screens (e.g. the Knowledge Shorts quickstart) let you enter the connection or API key a recipe needs without ever leaving that screen. Previously you’d have to open a new tab, go all the way to the Integrations hub, and copy a value back over; now you can paste the key straight into a field on the page and it’s saved securely right there, and for a connection that needs an external sign-in, the page automatically checks in the background for when it’s done — no separate “I’m finished” button to click before moving on.

Verifying your email for notifications

Besides external services like GitHub or Notion, an agent that wants to email you reports or alerts (the Agent Email skill) needs your email address verified first. This verification doesn’t happen in the Integrations hub above — it lives at Settings → Profile : (A) the email card at the top of the Profile page, where you enter a 6-digit code sent to your address; (B) in the agent’s Skill Selector, toggling on Agent Email shows an “Email verification required” row with a Verify button; (C) a verification card the agent posts in the chat the moment it needs to send mail. Verify once and you won’t need to again — the agent can only ever email the address you verified, never a third party. The one exception: an agent that belongs to an enterprise (managed-contract) organization is released from this limit and can email external recipients (customers, partners) on the organization’s behalf. Even then, only replies from people the agent emailed first wake it — mail from unknown senders is stored but never starts a run.

What happens after connecting

• Whenever an agent runs a skill that uses the connected service, UpServe fetches a valid access token and hands it to that skill.
• The token is cleaned up at the end of the skill’s run. It’s fetched fresh next time.
• Refresh happens right when a skill is about to run, not on a background schedule, so work in progress rarely stalls.
• The skill card shows Reconnect required in two cases: (1) the external service revoked access — for example you changed your password or removed the integration from the provider’s settings; or (2) the connection is still active, but a skill needs a permission that was added after you first connected (so the existing connection doesn’t cover it yet). Clicking the prompt reopens the consent flow either way.

The account organization-shared agents use

When an agent is used by an organization (a company or team) rather than just you, the account it uses to reach Notion, Slack, GitHub, and similar services is chosen ahead of time by an organization owner (OWNER) by default. It doesn’t matter who is currently chatting with the agent, or whether it’s running on its own on a schedule — it always uses the same account. This keeps a member chatting with the agent during the day and a scheduled run at night from ever seeing two different accounts.

• Organization owners can open a service card in the Integrations hub and look at the Organization connection section to see which account is currently designated for each service, and to designate their own connection as that account (or remove the designation). To designate one, you need to have connected that service to your own account first. Owners can always designate, replace, or remove a designation.
• Members can also designate their own account for specific services. When an owner turns on “Allow members to designate their own account” for a service in that same section, any member can claim that service’s unclaimed slot with their own account. Turning the switch on notifies every member, so anyone interested knows to act.
  • Once a slot is filled, members can’t overwrite it — only an empty slot can be claimed this way, so no one can bump another member’s account. Ask an owner if the account needs to change.
  • A member who designated their own account can remove that designation themselves, the same as an owner can. They can’t remove someone else’s.
  • Turning the switch off doesn’t remove an account a member already designated — it only blocks new designations going forward, so the organization’s agent doesn’t lose the service without warning.
• For a service where this switch is off, members can see the current designation on that screen but can’t change or remove it.
• Connecting your own account doesn’t change a service that has no designation yet. Designating is a separate step only an owner (or, where opened up, the account’s own member) can take, so simply connecting your own account doesn’t automatically become the account the shared agent uses. In that case the agent lets people know an owner needs to designate an account, and work that needs that service waits until they do.
• This section only appears for users who belong to an organization. An agent you use on your own doesn’t need this step — it simply uses the account you connected, as described everywhere else on this page.

Note — this designation decides which account is used to reach a service. It’s a separate feature from the “Saved keys” access/deletion rules described further down this page.

Disconnect / re-authenticate

To disconnect, open the Integrations hub , click the service’s card, and use the Disconnect button in the detail panel — this works regardless of whether you have a skill for that service installed.

If the service’s skill is installed in My Library, that skill card also shows a Disconnect button next to the connected account name, giving you the same action in one more place.

The OAuth row inside the agent’s Skill Selector only offers a Reconnect button — that reopens the consent screen to re-authenticate, it does not disconnect.

After disconnecting, any skill that uses that service will ask you to connect again on its next run. To swap to a different account, disconnect and then reconnect with the new one.

Note — Disconnecting removes the connection for all of your agents that use that service. If you only use agents on your own, this has no effect on anyone else. But if this connection was the one designated above under “The account organization-shared agents use,” that organization’s agents lose access to the service too — every member’s chats and its automatic runs alike. The disconnect dialog tells you which organizations rely on the account, and the organization’s owners are notified.

To undo it — reconnect the same account within 14 days and the designation is restored automatically. Connecting a different account, or reconnecting after 14 days, does not restore it; someone with the authority to designate (an owner, or the member themself if that service is still open to members) then has to designate a new account. (This exists for the common case of disconnecting briefly to re-authenticate.)

Connecting more services

The GitHub, Linear, Notion, and Slack connections covered above support both a one-click OAuth sign-in and an alternate MCP (Model Context Protocol — the standard way an agent calls an outside service’s features) connection method for the same service — open that service’s card in the Integrations hub and you’ll see both, with OAuth recommended by default since it has less friction. Some services only offer sign-in (Google Calendar, Drive, Tasks); others are MCP-only — automation hubs (Zapier), project management (Asana, ClickUp), docs and knowledge bases (Atlassian), sales and payments (HubSpot, Stripe), design and video (Canva, Figma, Higgsfield, OpusClip, VEED), website management (Webflow), and scheduling (Calendly). Even for the same provider, a connection made via OAuth and one made via MCP are treated separately — you connect each one on its own.

• Where — the Integrations hub , from the category-grouped cards. No need to look up a service’s address yourself. If a service isn’t listed, use + Register a server not listed here in the Advanced area at the bottom of the hub to add one by address. This manual registration screen works the same way on web, iOS, and Android.
• What happens next — most services in the list use sign-in, so picking one takes you straight to that service’s login screen; approve the permissions and the connection is done. (If you enter a server yourself that uses an API key, paste the key and click Test connection to preview the features it makes available — only then can you register it.)
• To use it on an agent — registering a server doesn’t automatically make it available everywhere. Go to the agent page → Settings tab → External MCP section and turn on the servers you want that agent to use. See Equipping Tools for details.

Deciding whether tool calls need approval every time

Expand a server in the agent’s External MCP section and you’ll see an on/off switch for each of its features, plus an Auto-approve tool calls switch for the server as a whole.

• Off (default) — every call to that server shows an approval card first, and you have to approve it to run.
• On — calls run immediately with no approval card. If a call also needs a credential from the “Saved keys” section above, that credential still requires its own approval even with this switch on.

Reference material and preset prompts connect too, not just features

Some services offer more than callable features (tools) — reference material (documents, lists) or preset prompt templates you can reuse. When a service offers these, they appear in the External MCP section alongside its tools and can be turned on or off individually the same way.

Managing servers you’ve registered

Servers outside the catalog (added by address) are managed in the Advanced area at the bottom of the Integrations hub. MCP connections for a catalog service (Notion or Zapier, for example) are managed right in that service’s own detail panel.

• See each server’s connection status (Active / Not connected / Error) and when its feature list was last checked. An Error status shows the reason.
• Click Refresh tools to check the service again for features that were added or removed. If anything changed, you’ll see what was added, removed, or changed before clicking Apply changes to make it active.
• For a server connected with an API key, Replace token swaps in a new value.
• Delete removes the server — every agent that used it loses access to its features.

Skills that connect with an API key (automatic setup card)

Instead of opening a login screen like GitHub or Slack, some skills need an API key you’ve obtained yourself — for example, an SMS-sending skill that needs an API key, a secret, and a registered sender number. When one of these skills is missing a required value, a setup card appears automatically in the chat the moment the agent tries to use it, walking you through what’s needed and where to get it.

1. The moment the agent needs the skill, a “Set up [Skill]” card appears in the chat.
2. For each required value, the card shows its name, a short description, and a link straight to the page where you obtain it.
3. Get the value from that link, paste it into the card’s input field, and click Save.
4. Once every required value is saved, the skill is ready to use. If a feature only needs a subset of the values, that feature is marked “ready” as soon as its subset is complete, even if other values are still missing.
5. Some values represent a step that takes time outside UpServe — such as an external review process. Mark those done from the card once they’re complete.

Values entered in this card are stored the same secure, per-agent way as the “Saved keys” described below, and you can also enter or view them by opening that service’s card in the Integrations hub .

Saved keys (credentials you store yourself)

Even for services without a prebuilt connection, you can store an API key or token so an agent reuses it across tasks — for example, save a payment-service API key once and the agent uses it without asking again.

• How to save (in chat) — when you enter a value with the lock button in the chat box, fill in the “What is this for?” field with a short description (e.g. “Stripe live API key”). Adding a description saves it by default, and UpServe names it automatically from that description (e.g. STRIPE_LIVE_API_KEY). To use it once without saving, check “One-time use (don’t save)” instead. If you want to pick the name yourself or overwrite an existing saved key, expand Advanced to choose that. Click Add another credential to enter several values at once — for example a username and a password — in a single send, up to 10 items. Each item gets its own description and is saved separately.
• How to save (from the hub directly) — you can also click + Add a key in the Saved keys section under the Advanced area at the bottom of the Integrations hub  and enter the agent, name, and value directly.
• Manage — view and delete them per agent in that same section.
• Private to the agent — a saved key is used only by that agent when it runs. For an agent you use alone, no one else ever sees it. For a key stored on an organization-shared agent, other members of that organization can see its name and purpose in this same list — never the value — and only an organization owner can delete it.
• Never shown again — for security, the stored value is never displayed again. To change it, delete and save a new one.
• No auto-refresh — unlike the OAuth connections above, a key you store yourself does not refresh automatically. Replace it when it expires.
• Remembered destinations — once you let a tool use this key (by approving it on a card the agent showed you), UpServe remembers that combination so automatic runs — like scheduled tasks — won’t ask again. Remembered destinations show up as tags in the same section; click the × on a tag to remove just that one. After removing it, the next use asks for approval again.
• Changing the value (overwrite) — saving a new value over an existing key shows a confirmation dialog asking whether to keep the destinations remembered above. It defaults to off: even with the same name, the new value might belong to a different service, so the previous value’s auto-approvals aren’t carried over automatically. If you’re just rotating the same secret, check Keep existing approvals in that dialog.

Agent direct access

Sometimes an agent needs to send a request straight to an external service using a stored credential or a connected account — for example, calling a service’s API directly from code. Even then, the agent never sees the actual password or token — UpServe passes it along securely in between.

• Approval card — the moment an agent needs this kind of access, it shows an approval card in the chat. The card summarizes which credential, which service, and what kind of request would be allowed. Once you approve, the agent won’t ask again for requests within that same scope.
• Review — the Agent direct access section under the Advanced area at the bottom of the Integrations hub  lists everything you’ve approved so far (the section only appears once you’ve approved at least one). Each entry shows which credential, which agent, which destination and requests it covers, and how many times it’s been used today (against its limit, if one is set).
• Revoke — click Revoke access on any entry to block it immediately. If the agent needs the same access again later, it shows a new approval card.

Note — Revoking only affects that one entry. It doesn’t change any other approval for the same service under a different credential or agent.

One-time secrets (values that are not stored)

For values you don’t want kept — a password or a verification code — send them with the lock button but leave the save option off. Your plaintext value is not stored; the encrypted value is automatically deleted a short time later (up to 15 min). Only the label and a masked placeholder remain in the conversation. Here too, Add another credential lets you enter values like a username and password together, up to 10 items in one send.

Security

• Per-user isolation (values only) — the actual value of a credential (a password or token) is stored against your account only, and no other user or team member can retrieve it. A key stored on an organization-shared agent is the one exception on visibility, not value: its name and purpose can be seen by other members of that organization — the value stays hidden either way. See “Saved keys” above for details.
• Saved keys are per-agent — a key you store yourself is encrypted for that agent only and is never exposed to external visitors of a shared link.
• The agent never sees the raw token — tokens are passed to the skill’s execution environment as environment variables only, and cleaned up when the run ends. They are not echoed into chat messages or logs. Agent direct access requests go further: the credential never enters the agent’s execution environment at all — UpServe’s server attaches it to the request on the agent’s behalf.
• Encrypted at rest — both the access token and refresh token are encrypted before being saved to the database.
• Standard OAuth + CSRF-safe — UpServe uses the standard Authorization Code flow and rejects forged callbacks.

Advanced

The rest of this page describes internal behavior — useful if you author skills directly or need to debug an integration. Day-to-day users can skip it.

Permissions requested per service

UpServe asks for the following scopes (user-facing summary; the actual consent screen comes from each service):

The consent screen is always the external service’s official page. The exact scopes granted are stored alongside the connection.

Resolution order for organization designations

Each time an agent runs, which account it uses is decided in this order:

1. If the organization has a designated connection for that service, it uses that connection — the same rule applies whether an owner or an opened-up member designated it.
2. If there’s no designation and the agent is owned by a single person (no organization), it uses that owner’s own connection — nothing changes if you work alone.
3. If there’s no designation and the agent belongs to a multi-member organization, it uses no account at all. It never falls back to the personal connection of whoever is currently chatting — that fallback is exactly what used to cause different members to see different accounts, so it was deliberately removed.

Managing the designation itself (creating, replacing, or removing it) defaults to organization owners (OWNER). When an owner turns on “allow members to designate” for a given service, a member can claim that service’s empty slot with their own account and later remove their own designation — an already-filled slot can never be overwritten by another member. Viewing the current designation is open to every member; only an owner can flip the policy switch itself.

How skills receive the credential

You only need this if you author skills directly or want to understand an imported skill’s internals. A skill’s SKILL.md declares the credentials it needs under metadata.requires, and at run time UpServe injects a valid token (refreshed first if near expiry) as an environment variable, then cleans it up when the run ends. Agents fill this field in automatically when packaging a skill, so you rarely edit the yaml yourself. See Creating Skills → Secret injection for the mapping table and examples.

How the API-key setup card (BYOK) works

When a skill’s definition declares setup.fields (values the user enters directly) and setup.external_steps (steps that take time outside UpServe, like an external review), UpServe renders a setup card containing only the values still missing whenever the agent tries to load that skill. Values entered on the card are encrypted and stored the same way as “Saved keys” above, scoped to that agent only; once a value is filled in, its row is marked done on the card. If a skill declares capabilities (named bundles of values), a capability unlocks as soon as all the values it needs are present, even while other values on the card remain outstanding. This inline chat card currently renders in the web app only — it is not yet implemented in the iOS or Android apps. The same value-entry form is available in the Integrations hub’s BYOK section on all three platforms (web, iOS, Android), though, so on mobile you fill in values from the hub rather than from the chat.

Google Drive Picker

When a skill or agent action needs to access Google Drive files, UpServe uses the Google Picker — a file selector that runs inside your browser under your Google account. Only the files you explicitly select through the Picker are accessible; UpServe does not request access to your entire Drive. This is enforced by the drive.file scope, which is limited to files the user has opened or created through the app.

Token expiry and refresh

• When an access token is close to expiry (within 5 minutes), UpServe uses the stored refresh token to mint a new one at the moment a skill requests it — right before the skill runs. There’s no separate background job that refreshes tokens ahead of time.
• Refresh happens just before the skill runs, so the new token is the one handed to the skill.
• If refresh fails (the user revoked access externally, or the refresh token was rotated out), the connection is marked inactive and the skill card surfaces a Reconnect required prompt for the user to consent again.

What decides the MCP connect button on a chat card

When an agent runs into an MCP server it needs but isn’t connected yet, it shows a connect button on a card. The server always decides which server that button points to and what happens when it’s pressed — an agent’s own claimed server name or address is never trusted as-is.

• The server behind the button must be owned by you (or your organization), Active, and not need re-authentication — the same bar used for the connectable candidates shown in the agent’s External MCP settings.
• If a server registered at the same address already exists (even if it was connected through a different agent), the button connects that one directly. If none exists yet, the button takes you to registration instead.
• The button’s label (the server’s name) always comes from the server, never from anything the agent wrote — long names are truncated.
• A single card can carry at most 3 jump buttons.
• If a lookup fails or points at an unknown server, that one button is silently dropped and the rest of the card still renders normally.

How MCP server registration works

Whether picked from the list or entered by address, a server goes through the same validation on registration (HTTPS is required, among other checks) — an entry from the curated list isn’t trusted any more than one you type in yourself. UpServe only supports remote servers reachable over HTTPS; a server that only runs on your own machine can’t be connected. Authentication is one of: no authentication, API key (Bearer), custom header, or sign-in (OAuth).

The MCP tool list is pinned at registration/refresh time

The feature list saved and used at runtime is a snapshot taken the moment you register the server or apply a Refresh tools update. If the service quietly changes what a feature does afterward, that change has no effect until you check and apply a refresh yourself — this keeps what you reviewed at registration time in sync with what actually runs.

Item limit on lock-button input

When you send several items at once with the lock button in chat — whether saved or one-time — a single send can hold up to 10 items. The screen and the storage step share the same limit.

How “remembered destinations” are removed

The “remembered destinations” tags in the Saved keys section are removed one at a time, by a request scoped to that single item — the whole list is never replaced in one call. This keeps a removal made in one browser tab from accidentally undoing something newly remembered in another.

Scope of an agent direct access approval

An agent direct access approval is valid only within the scope you approved at the time (the target service address and the kind of request). Requests outside that scope are automatically denied, and the agent shows a new approval card if it needs a wider scope. If an entry has a daily call limit, no further requests go through once that limit is reached for the day.