Version 1.1 · 21 October 2026 · For partner administrators
The 1Stream Partner API is also an MCP server (Model Context Protocol, the open standard AI assistants use to reach outside tools). Connected to it, an assistant such as Claude can list your phone systems, look up extensions and queues, check health and live calls, review call history with its CRM links, run reports and, when you allow it, make changes, all under your own 1Stream account. You decide what it may do with an access level chosen when you connect, every change needs your explicit confirmation, and you can see and disconnect every connected assistant from the Control Portal.
1. Before you start
You need:
- A Control Portal account that can manage Partner API keys for your 1Stream account.
- A Partner API key created with "Allow hosted AI assistants" enabled. Claude.ai, Claude Desktop, the Claude mobile apps and any other assistant that runs in its vendor's cloud call 1Stream from the vendor's addresses, and this option is what lets those calls in. An assistant that runs on your own machine or on a server whose address is on the key's allowlist, such as Claude Code or a self-hosted agent, does not need it.
- An assistant that supports remote MCP servers with OAuth sign-in. Claude (web, desktop, mobile and Claude Code) is the worked example below; other MCP clients follow the same steps.
Note: The key's own access level (Full, Read only or Operations) is the ceiling. An assistant can be granted that level or a narrower one, never a wider one.
2. Create an API key for the assistant
- Sign in to the Control Portal as an administrator and open the Partner API page.
- Choose Create API key and give it a name you will recognise, for example Claude connector.
- Tick Allow hosted AI assistants. It can only be set when the key is created.
- Pick the key's access level. Start with Read only if you want to try the connection first; you can create another key later.
- Leave the Allowlist empty unless you also plan to call the API directly from your own systems with this key. It never applies to a hosted assistant.
- Choose Create and copy the API key ID and the secret. The secret is shown once. You will enter them together as
apiKeyId:secret.
Note: An existing key created without the hosted-assistant option cannot be changed; create a new key. Keys created for hosted assistants show a badge in the key list.
3. Connect from your assistant
Choose the address for your region
Use the host that serves the region where your 1Stream systems are hosted. Any host also forwards you to your home region, so a wrong choice still works, but every call then makes an extra hop.
| Region | Server address |
|---|---|
| United States | Intentionally Removed from public document |
| Europe | Intentionally Removed from public document |
| Australia | Intentionally Removed from public document |
1Stream partners will find the URL's to these regions inside of the Control Portal after you sign-in with a valid account.
When you add 1Stream as a custom connector you can also fix the access level in the address: /mcp offers the full catalogue, /mcp/read only the read tools and /mcp/ops only the operations set. When you connect from the Claude connector directory, the level is chosen on the sign-in page instead (section 4).
Claude.ai, Claude Desktop and the Claude mobile apps
- From the directory (once 1Stream is listed): open Customize > Connectors, find 1Stream, pick your region and choose Connect.
- As a custom connector: open Customize > Connectors and choose Add custom connector. Enter a name, for example 1Stream, and the server address for your region. Leave the OAuth client ID and client secret fields empty; the connector registers itself. Choose Add, then Connect. On Team and Enterprise plans an organisation owner may need to add the connector under Admin settings > Connectors first.
- The 1Stream sign-in page opens. Complete it as described in section 4. You are returned to Claude with the connector connected.
- In a chat, turn the connector on from the + menu and ask, for example, "List my phone systems."
Connectors added on claude.ai are available in Claude Desktop and the mobile apps for the same account.
Claude Code
claude mcp add --transport http 1stream [URL intentionally removed]
claudeInside Claude Code type /mcp, select 1stream and choose Authenticate. A browser window opens the 1Stream sign-in page. Claude Code runs on your machine, so it does not need a key created for hosted assistants if your address is on the key's allowlist; a hosted-assistant key works too.
Other MCP clients and your own agents
- Any client that supports remote MCP servers over Streamable HTTP with OAuth 2.0 and PKCE can connect. The server supports dynamic client registration and client ID metadata documents, so no client has to be registered with 1Stream in advance. Discovery metadata is published at the standard well-known locations of each host.
- An agent you host yourself can skip OAuth and send the key on every request in an
X-Api-Key: apiKeyId:secretheader. Its address must then be on the key's allowlist.
4. Sign in and choose the access level
Whichever assistant you use, connecting opens the 1Stream sign-in page. It shows the assistant's name and the address the assistant will be sent back to once you connect. Check that the address belongs to the assistant you are using.
- Enter the API key as
apiKeyId:secret, exactly as the Control Portal showed it. - Choose what the assistant may do. Read only is preselected.
- Choose Connect.
| Access level | What the assistant can do | Typical use |
|---|---|---|
| Read only | Look things up, check health and run reports. Nothing is changed. | Reporting, answering questions, a first connection. |
| Operations | The support-desk set: health, live calls, queue and agent status, logs, availability, blocked numbers and IP lists, holidays, service restarts and reboots, plus the call history, call statistics and queue login history recorded by 1Stream. No provisioning. | A support or operations assistant. |
| Full access | Everything the key can do, including creating, changing and deleting extensions, trunks, rules, IVRs, queues and departments. | Administration and provisioning. |
A key limited to Read only or Operations can only be granted its own level; the page tells you which level to pick. To change an assistant's level later, disconnect it (section 7) and connect again.
Tokens. The assistant receives a one-hour access token that it refreshes automatically. A connection stays valid while it is used and expires after 45 days without use, after which you connect again. Disabling, rotating or removing the key disconnects every assistant that uses it at once.
5. Using the assistant
- Start with your phone systems. Most tools need a phone system id. The assistant finds it with List phone systems first, so "list my phone systems" is a good first question.
- Reads run without confirmation. Looking things up, health checks and reports never change anything. Your assistant may still ask you once before using a tool for the first time; in Claude you can set the read-only tools to Always allow.
- Changes need your explicit confirmation. Every tool that changes or removes live configuration is marked as such, and 1Stream refuses it unless the assistant confirms the exact action with you first. The refusal describes what confirming would do (for example, which numbers a trunk carries before it is deleted), so you see the impact before you agree. Nothing is changed until you confirm.
- Tools that act across many systems offer a dry run, which lists what would be affected and changes nothing.
- High-availability pairs. A standby system whose primary is running answers only status, time and service reads. During a failover both systems accept reads only, and changes are made in the Control Portal until the primary is restored. Status of the account's high-availability pairs explains the state of each pair.
- Errors carry a correlation id. Every error result includes the reason and a correlation id. Quote the id to support.
- Text from your phone systems is data, not instructions. Names, status messages, phonebook entries and log lines were typed by the systems' users. The assistant is told to report them and never to follow them as instructions.
6. What the assistant can do
The full catalogue has 131 tools: 76 read, 6 create and 49 change. The Read only and Operations levels see a subset. Each area below lists its tools.
| Type | Meaning |
|---|---|
| Read | Looks things up. Nothing is changed. |
| Create | Adds a new item. Your assistant asks you before it uses the tool. |
| Change | Changes or removes live configuration. Refused by 1Stream unless you have confirmed the exact action. |
The Call history and CRM data from 1Stream tools answer from what the 1Stream integration recorded for a phone system, not from the system itself. They need a 1Stream account connected to that system with at least one Intelligence or Power seat. A system without a connected account answers "not found" and one without such a seat answers a refusal; neither is a fault of the system.
Phone systems and health (13 tools: 10 read, 0 create, 3 change)
| Type | What it does | Tool name |
|---|---|---|
| Read | List phone systems | list_pbx |
| Read | Get phone system status | get_pbx |
| Read | Health check of one phone system | get_pbx_health |
| Read | Health check across phone systems | get_estate_health |
| Read | Status of the account's high-availability pairs | get_failover_status |
| Read | Get the phone system's current time | get_server_time |
| Read | List phone system services | list_services |
| Change | Restart phone system services | restart_services |
| Read | Get reboot schedule and reboots in progress | get_reboot_status |
| Change | Reboot a phone system now | reboot_pbx |
| Change | Cancel a queued reboot | cancel_reboot |
| Read | List configuration parameters | list_parameters |
| Read | Identify the current credential | whoami |
Extensions and users (18 tools: 11 read, 1 create, 6 change)
| Type | What it does | Tool name |
|---|---|---|
| Read | List users and extensions | list_users |
| Read | Find an extension | find_extension |
| Read | Find a user by email address | find_by_email |
| Read | Find a person across phone systems | find_person_in_estate |
| Read | Everything about one extension | get_extension_overview |
| Create | Create an extension | create_extension |
| Change | Update an extension | update_extension |
| Change | Delete an extension | delete_extension |
| Read | List an extension's phones | list_extension_devices |
| Read | List provisionable phone models | list_phone_templates |
| Read | List an extension's forwarding profiles | list_profiles |
| Change | Switch an extension's profile | select_profile |
| Change | Set a profile's status message | set_profile_message |
| Change | Apply or clear a temporary profile override | set_profile_override |
| Change | Mark an extension away until a time | set_extension_away |
| Read | List voicemails | list_voicemails |
| Read | List dialable destinations | list_peers |
| Read | List the company phonebook | list_phonebook |
Call queues and ring groups (15 tools: 7 read, 2 create, 6 change)
| Type | What it does | Tool name |
|---|---|---|
| Read | List call queues | list_queues |
| Create | Create a call queue | create_queue |
| Change | Update a call queue | update_queue |
| Change | Delete a call queue | delete_queue |
| Read | List queue agents | list_queue_agents |
| Read | Who is staffing a queue right now? | get_queue_staffing |
| Read | Get an extension's queue login state | get_queue_status |
| Change | Log an extension in to or out of its queues | set_queue_status |
| Change | Log a queue agent in or out | set_queue_agent_status |
| Read | Queue performance over a period | queue_performance_summary |
| Read | List ring groups | list_ring_groups |
| Read | Get a ring group | get_ring_group |
| Create | Create a ring group | create_ring_group |
| Change | Update a ring group | update_ring_group |
| Change | Delete a ring group | delete_ring_group |
IVRs and call flow apps (10 tools: 6 read, 1 create, 3 change)
| Type | What it does | Tool name |
|---|---|---|
| Read | List IVRs (digital receptionists) | list_ivrs |
| Read | Get an IVR | get_ivr |
| Create | Create an IVR | create_ivr |
| Change | Update an IVR | update_ivr |
| Change | Delete an IVR | delete_ivr |
| Read | List call flow apps | list_call_flow_apps |
| Read | Get a call flow app | get_call_flow_app |
| Read | List a call flow app's files | get_call_flow_app_files |
| Read | Get a call flow app's console link | get_edit_url |
| Change | Replace a call flow app's script | update_call_flow_app_script |
Trunks, numbers and routing (14 tools: 6 read, 0 create, 8 change)
| Type | What it does | Tool name |
|---|---|---|
| Read | List SIP trunks | list_trunks |
| Read | Get a SIP trunk | get_trunk |
| Change | Create a SIP trunk | create_trunk |
| Change | Update a SIP trunk | update_trunk |
| Change | Delete a SIP trunk | delete_trunk |
| Read | List direct-dial numbers | list_dids |
| Change | Assign a direct-dial number | assign_did |
| Change | Unassign a direct-dial number | unassign_did |
| Read | Where does a direct-dial number ring? | trace_inbound_number |
| Read | List outbound rules | list_outbound_rules |
| Read | Get an outbound rule | get_outbound_rule |
| Change | Create an outbound rule | create_outbound_rule |
| Change | Update an outbound rule | update_outbound_rule |
| Change | Delete an outbound rule | delete_outbound_rule |
Departments, holidays and emergency rules (14 tools: 5 read, 1 create, 8 change)
| Type | What it does | Tool name |
|---|---|---|
| Read | List departments | list_departments |
| Read | List department members | list_department_members |
| Create | Create a department | create_department |
| Change | Update a department | update_department |
| Change | Delete a department | delete_department |
| Read | List a department's holidays | list_holidays |
| Change | Add a holiday to a department | add_holiday |
| Change | Remove a holiday from a department | remove_holiday |
| Change | Add a holiday to every department across phone systems | add_holiday_everywhere |
| Read | List emergency rules | list_emergency_rules |
| Read | Get an emergency rule | get_emergency_rule |
| Change | Create an emergency rule | create_emergency_rule |
| Change | Update an emergency rule | update_emergency_rule |
| Change | Delete an emergency rule | delete_emergency_rule |
Blocked numbers and IP lists (7 tools: 3 read, 0 create, 4 change)
| Type | What it does | Tool name |
|---|---|---|
| Read | List blocked caller numbers | list_phone_blacklist |
| Change | Block a caller number | add_phone_blacklist_number |
| Change | Unblock a caller number | remove_phone_blacklist_number |
| Read | What do we know about a phone number? | investigate_caller |
| Read | List IP allow/block list | list_ip_blocklist |
| Change | Add an IP list entry | add_ip_blocklist_entry |
| Change | Remove an IP list entry | remove_ip_blocklist_entry |
Hold music, prompts and notifications (13 tools: 6 read, 1 create, 6 change)
| Type | What it does | Tool name |
|---|---|---|
| Read | Get the hold-music settings | get_music_on_hold |
| Change | Replace the hold-music settings | set_music_on_hold |
| Read | List the audio available for hold music | list_hold_music_prompts |
| Read | List audio prompts | list_prompts |
| Change | Delete an audio prompt | delete_prompt |
| Read | List hold-music playlists | list_playlists |
| Read | Get a playlist | get_playlist |
| Create | Create a playlist | create_playlist |
| Change | Replace a playlist's settings | update_playlist |
| Change | Delete a playlist | delete_playlist |
| Change | Remove a file from a playlist | remove_playlist_file |
| Read | Get the system-notification settings | get_notification_settings |
| Change | Replace the system-notification settings | set_notification_settings |
Microsoft 365 (5 tools: 3 read, 0 create, 2 change)
| Type | What it does | Tool name |
|---|---|---|
| Read | Get the Microsoft 365 integration settings | get_m365_configuration |
| Change | Change the Microsoft 365 integration settings | update_m365_configuration |
| Read | List the Microsoft 365 users that could be synced | list_available_m365_users |
| Read | List the Microsoft 365 users being synced | list_synced_m365_users |
| Change | Add a Microsoft 365 user to the sync | sync_m365_user |
Management portal users and roles (4 tools: 4 read, 0 create, 0 change)
| Type | What it does | Tool name |
|---|---|---|
| Read | List management portal users | list_portal_users |
| Read | Get a management portal user | get_portal_user |
| Read | List management portal roles | list_portal_roles |
| Read | Get a management portal role | get_portal_role |
Active calls, recordings and logs (6 tools: 4 read, 0 create, 2 change)
| Type | What it does | Tool name |
|---|---|---|
| Read | List active calls | list_active_calls |
| Change | Place a call from an extension | place_call |
| Change | End an active call | drop_call |
| Read | List call recordings | list_recordings |
| Read | List the phone system's event log | list_event_log |
| Read | Search the phone system's application log | search_logs |
Call history and CRM data from 1Stream (6 tools: 5 read, 0 create, 1 change)
| Type | What it does | Tool name |
|---|---|---|
| Read | Call history with CRM links | integration_call_logs |
| Read | Call legs | integration_call_segments |
| Read | Call statistics | integration_call_statistics |
| Read | Queue login history | integration_queue_agent_history |
| Read | CRM user mappings | integration_crm_user_mappings |
| Change | Fire an on-call rule | integration_signal_event |
Reports and reporting data (6 tools: 6 read, 0 create, 0 change)
| Type | What it does | Tool name |
|---|---|---|
| Read | List the phone system's own reports | list_reports |
| Read | Describe a report's arguments and columns | describe_report |
| Read | Run one of the phone system's own reports | run_report |
| Read | List the queryable reporting tables and views | list_tables |
| Read | Describe a queryable table or view | describe_table |
| Read | Run a read-only query over the reporting data | query |
7. Manage and disconnect assistants
In the Control Portal, the Partner API page shows a Connected assistants panel under your keys: each connection with the assistant's name, its access level, the key it uses, when it last refreshed its access and when the connection expires.
- Disconnect ends a connection at once. The assistant has to sign in again to reconnect.
- Rotating, disabling or removing a key disconnects every assistant that uses it.
- You can also remove the connector from the assistant's own settings (in Claude, Customize > Connectors). Doing it in the Control Portal is the sure way, because it ends the connection on the 1Stream side.
8. Limits
- 60 requests per minute per key. An assistant that exceeds it is told to slow down and retries.
- Large lists are paged. The assistant asks for more pages when it needs them.
- Cross-system tools work on up to 25 systems per call and name the systems they left out so the next call can be scoped.
-
The tool catalogue is loaded at the start of a conversation. Identify the current credential (
whoami) reports the catalogue revision; after a server update, start a new conversation or reconnect to use the new tools.
9. Troubleshooting
| What you see | Cause and fix |
|---|---|
| "Couldn't reach the server" when adding the connector | The address has a typo or is not HTTPS. Check the table in section 3 and the /mcp ending. If your network filters outbound traffic, allow the 1Stream host for your region. |
| The sign-in page says the key was not accepted | A typo, the wrong key, or a disabled key. Enter the whole apiKeyId:secret as the Control Portal showed it; create a new key if the secret was lost. |
| The sign-in page asks you to choose another access level | The key is limited to Read only or Operations and you chose a different level. Choose the key's own level, or create a Full access key. |
| "Authorization failed", or connected but every request is refused | From Claude.ai, Desktop or mobile: the key was created without Allow hosted AI assistants, so the assistant's calls are stopped by the key's allowlist. Create a new key with the option and connect again. From Claude Code or your own agent: add your address to the key's allowlist, or use a hosted-assistant key. |
| "Too many requests" (429) | The key's limit of 60 requests per minute was reached. Wait a minute; the assistant retries. Give each assistant its own key if several share one. |
| The assistant does not offer a tool you expected | The access level decides the tool set. Disconnect in the Control Portal and connect again with a wider level, or use a key with a higher level. |
| A tool answers "Session not found", or the tools seem out of date | The conversation holds the catalogue it started with. Start a new conversation, or reconnect the connector. |
| "This phone system is a standby" or "reads only during a failover" | The system is one half of a high-availability pair. Ask for the pair's status, then work on the system that is serving; changes during a failover are made in the Control Portal. |
| A change does not show yet, or a change timed out | A timeout or an unreachable system does not mean the change was skipped. Ask the assistant to read the item back before it retries, so a change is never applied twice. |
| A call history or CRM tool answers "not found" or a refusal | These tools read what the 1Stream integration recorded. The phone system needs a connected 1Stream account with at least one Intelligence or Power seat. Contact support if the account is connected and the seat is in place. |
| It worked and then stopped | Someone rotated or disabled the key, disconnected the assistant in the Control Portal, or the connection was unused for 45 days. Connect again with a live key. |
10. Data handling and privacy
When an assistant uses this connector, 1Stream receives the tool calls the assistant makes (the tool name and its arguments) and answers with phone-system configuration and operational data the key can already access: for example extensions and users, queues, trunks, call history and recording metadata, voicemail metadata, blocked numbers and IP lists, and, for systems connected to a 1Stream account, the call history the integration recorded with the CRM contact and ticket linked to each call, call summaries where the account has that service, call legs, queue login history and the mapping of 1Stream users to CRM members. With your confirmation an assistant can also place a call from an extension or fire one of your on-call notification rules. 1Stream records request metadata (time, address, key, tool, status and correlation id) for operations and security, and an audit trail of configuration changes naming the key that made them.
1Stream never receives your conversation, the assistant's memory, chat history or files you uploaded to the assistant. What the assistant does with the answers is governed by the assistant vendor's own terms. The 1Stream privacy policy is at https://www.1stream.com/privacy.
11. Support
Email support@1stream.com. Include the correlation id from the error, the time of the failing call in UTC, the region address you connected to and the name of the assistant. For sign-in problems, include the API key ID (never the secret).
1Stream Partner API · Connecting an AI assistant · Version 1.1 · 21 October 2026 · Privacy policy