For agents and technical readers

Connect and inspect an external source

Discover the actual interface, let the owner complete service consent and verify the connection separately from app execution and saved capture.

Contents

Authority and effects

Connection lifecycle is owner-controlled. A stored credential grants no app access by itself. Creating a connection or granting it to an app changes external data access; use the owner’s explicit scope. Never request or store the secret in the agent conversation.

This procedure describes the released Core connection and OAuth tools. A client may omit or restrict them. Discover the live tool schemas before calling. If unavailable, use the Portal owner route; do not invent an endpoint or another credential.

Discover existing state

Call orient with {} and verify the intended Mind and principal. Under owner authority, call list_connections with {}. Inspect the named connection’s type, non-secret configuration, app grants and last use. This tool never returns a secret.

To probe a known connection, call test_connection:

{"name":"google"}

The example names the Google capture connection; replace it with the actual approved name. Read the bounded reachable result. It is not a successful sensor run.

After the owner authorises read-only Gmail/Calendar access for the intended account, call oauth2_connect_start:

{"provider":"google"}

Give the owner the returned browser authorisation route. The owner completes account consent there. Keep the returned state tied to that attempt; do not accept an unrelated callback. Use the supported callback handler rather than pasting its code into a general chat.

Call oauth2_connect_poll with {} no faster than the returned interval. Continue only while its phase is pending. Connected establishes stored connection state; failed requires its named correction. After an uncertain response, inspect the current ceremony/connection before creating a new attempt.

Add an API-key connection through the Portal

Use Settings → Connections → Add a connection. The owner supplies the approved name, API key type, supported base URL/provider and secret into the protected form. The disabled Google option is not the Google OAuth flow.

For Telegram, the exact supported metadata is name telegram, provider telegram, base URL https://api.telegram.org; the bot token stays in the form. Follow the human bot-scope guide before granting access. Other providers require their actual supported connection configuration; do not infer arbitrary HTTP access from this form.

Grant only the intended installed app

Inspect list_available_apps with {} and the actual installed identity. Under owner authority, the released action shape is:

{"action":"app_grant_connection","item_id":"telegram-sensor","connection_name":"telegram"}

This is a Telegram example, not a substitute for identifying the intended app. Read the action result and inspect the grant again. Do not grant every connection to diagnose a missing one.

Verify and remove deliberately

Test the connection, then follow the normal scheduled capture and open the output. Record connection, installed app, run and saved-result states separately. Use the sensor procedure.

remove_connection takes name and optional boolean cascade. Active app grants refuse removal unless the owner explicitly authorises the cascade that revokes them. A Mind-typed peer connection uses the separate Network lifecycle; do not remove it with the generic service-connection route.

Related

Bring email, calendar events and files into your Mind · Install a selected sensor and verify capture · Connect and share through a Mind’s Network

Practical guides for people and agents

Start with one useful job

Join the waitlist

Plain text for AI agents. Same content as the human page.

## For agents

- What Mensara is: it gives a team its own Mind, one shared memory for the team and their AI agents, built by Xanadu Labs LLC.
- Status: signup is not open. A person joins the waitlist at https://app.mensara.ai/#waitlist. Agents cannot create an account or sign up.
- How you can help your person: explain what Mensara does, check whether it fits a job their team repeats, and share the waitlist link.
- Agent references: https://app.mensara.ai/llms.txt lists every page as Markdown and the tool input references for connected agents.

---

# Connect and inspect an external source

Operating procedures · For agents and technical readers · [How it works](https://app.mensara.ai/how-it-works)

Discover the actual interface, let the owner complete service consent and verify the connection separately from app execution and saved capture.

[Page as Markdown](https://app.mensara.ai/how-it-works/connect-source-procedure.md)

[Human guide](https://app.mensara.ai/how-it-works/connections-and-capture)

## Use the released interface with current authority

Availability: Core0.20.11 / Portal0.3.47 source checked; discover the actual installed client and enabled features.

Who can do this: The connected principal with the permissions named in this procedure

What changes: The procedure explains its actual reads, writes or external effects before action.

Limits: An input accepted by a source schema is not a successful installed-runtime task.; Keep human decisions, client exclusions and pending results explicit.

Verification: Source checked and independently reviewed; scoped runtime receipts are recorded separately.

## Authority and effects

Connection lifecycle is owner-controlled. A stored credential grants no app access by itself. Creating a connection or granting it to an app changes external data access; use the owner’s explicit scope. Never request or store the secret in the agent conversation.

This procedure describes the released Core connection and OAuth tools. A client may omit or restrict them. Discover the live tool schemas before calling. If unavailable, use the Portal owner route; do not invent an endpoint or another credential.

## Discover existing state

Call `orient` with `{}` and verify the intended Mind and principal. Under owner authority, call `list_connections` with `{}`. Inspect the named connection’s type, non-secret configuration, app grants and last use. This tool never returns a secret.

To probe a known connection, call `test_connection`:

```
{"name":"google"}
```

The example names the Google capture connection; replace it with the actual approved name. Read the bounded reachable result. It is not a successful sensor run.

## Start the Google consent ceremony

After the owner authorises read-only Gmail/Calendar access for the intended account, call `oauth2_connect_start`:

```
{"provider":"google"}
```

Give the owner the returned browser authorisation route. The owner completes account consent there. Keep the returned state tied to that attempt; do not accept an unrelated callback. Use the supported callback handler rather than pasting its code into a general chat.

Call `oauth2_connect_poll` with `{}` no faster than the returned `interval`. Continue only while its phase is pending. Connected establishes stored connection state; failed requires its named correction. After an uncertain response, inspect the current ceremony/connection before creating a new attempt.

## Add an API-key connection through the Portal

Use **Settings → Connections → Add a connection**. The owner supplies the approved name, **API key** type, supported base URL/provider and secret into the protected form. The disabled Google option is not the Google OAuth flow.

For Telegram, the exact supported metadata is name `telegram`, provider `telegram`, base URL `https://api.telegram.org`; the bot token stays in the form. Follow the human bot-scope guide before granting access. Other providers require their actual supported connection configuration; do not infer arbitrary HTTP access from this form.

## Grant only the intended installed app

Inspect `list_available_apps` with `{}` and the actual installed identity. Under owner authority, the released action shape is:

```
{"action":"app_grant_connection","item_id":"telegram-sensor","connection_name":"telegram"}
```

This is a Telegram example, not a substitute for identifying the intended app. Read the action result and inspect the grant again. Do not grant every connection to diagnose a missing one.

## Verify and remove deliberately

Test the connection, then follow the normal scheduled capture and open the output. Record connection, installed app, run and saved-result states separately. Use [the sensor procedure](https://app.mensara.ai/how-it-works/sensor-setup-procedure).

`remove_connection` takes `name` and optional boolean `cascade`. Active app grants refuse removal unless the owner explicitly authorises the cascade that revokes them. A Mind-typed peer connection uses the separate Network lifecycle; do not remove it with the generic service-connection route.

## Related

- [Bring email, calendar events and files into your Mind](https://app.mensara.ai/how-it-works/connections-and-capture)
- [Install a selected sensor and verify capture](https://app.mensara.ai/how-it-works/sensor-setup-procedure)
- [Connect and share through a Mind’s Network](https://app.mensara.ai/how-it-works/network-procedure)

[Join the waitlist](https://app.mensara.ai/#waitlist)