Composio Integration

The NexSpace toolkit on Composio makes the core workforce verbs available to LangChain, CrewAI, Vercel AI SDK, OpenAI Agents SDK, and any framework that uses Composio’s SDK. (For the full governed surface — category tools, research tools, approvals, connected apps — connect to the MCP server directly.)

Install

from composio import ComposioToolSet

toolset = ComposioToolSet()
tools = toolset.get_tools(apps=["nexspace"])

Connect

Composio handles the OAuth 2.1 + PKCE flow automatically:

entity = toolset.get_entity("default")
connection = entity.initiate_connection(app_name="nexspace")
print(connection.redirect_url)  # User opens this in browser

Available Tools

The published toolkit exposes the core NexSpace verbs as Composio tools:

NEXSPACE_FIND_CREDENTIALED_STAFF
NEXSPACE_FILL_SHIFT
NEXSPACE_PROPOSE_SHIFT_SCHEDULE
NEXSPACE_SWAP_SHIFTS
NEXSPACE_GET_FACILITY_COVERAGE
NEXSPACE_VERIFY_CREDENTIAL
NEXSPACE_LIST_EXPIRING_CREDENTIALS
NEXSPACE_SEARCH_STAFF
NEXSPACE_GET_STAFF_MEMBER
NEXSPACE_PREVIEW_PAYROLL_RUN
NEXSPACE_RUN_PAYROLL
NEXSPACE_NOTIFY_SHIFT_SWAP
NEXSPACE_QUALIFY_LEAD
NEXSPACE_SEARCH_LEADS
NEXSPACE_LIST_FACILITIES
NEXSPACE_GET_FACILITY

Example: LangChain Agent

from langchain.agents import create_openai_tools_agent
from composio_langchain import ComposioToolSet

toolset = ComposioToolSet()
tools = toolset.get_tools(apps=["nexspace"])

agent = create_openai_tools_agent(llm, tools, prompt)
agent.invoke({"input": "Find available staff for facility 12's morning shift"})

API Key Fallback

For environments where browser-based OAuth is impossible, the NexSpace toolkit manifest declares an API-key fallback (auth.fallback in tools/composio-toolkit/toolkit.json):

What to supply: a NexSpace personal access token (nex_pat_…). Mint one at Settings → API Keys. A PAT acts as the user it belongs to, which is what the toolkit’s tools expect.
How it is presented: as the Authorization header, formatted Bearer {api_key} — the same header shape as an OAuth access token, so nothing downstream changes.
Where it goes: it is the credential of the NexSpace connected account inside Composio, supplied when you create that connection.

Do not pass a NexSpace key to ComposioToolSet(api_key=…). That parameter is the Composio platform API key, not the downstream app credential — ComposioToolSet() keeps reading COMPOSIO_API_KEY for the Composio side. Putting a nex_ token there authenticates you to Composio with a token Composio does not recognize, and never reaches NexSpace.

We deliberately do not print a Composio SDK call signature for creating the connected account here: Composio’s client API is versioned outside this repo and cannot be verified from it, and a stale signature is exactly how the ComposioToolSet(api_key=…) mistake started. Follow Composio’s current docs for creating a connected account with an API-key auth scheme, and give it the token and header format above.

Connected apps over MCP (inbound)

Everything above is the outbound direction: NexSpace verbs published as a Composio toolkit that your LangChain/CrewAI agent calls. The inbound direction is the mirror image — the apps you have connected through NexSpace (Slack, QuickBooks, HubSpot, …) appearing as tools on the NexSpace MCP server, brokered through Composio, with NexSpace governance wrapped around every call. One connector in Claude or ChatGPT reaches your whole connected stack.

When a connected-app tool appears in `tools/list`

Both conditions must hold, per call:

The credential carries apps:read / apps:write. A read-only app tool needs apps:read; a mutating one needs apps:write. These are not in the default connector bundle — reaching into an owner’s outside SaaS has to be an explicit grant, so request them by name when you connect. apps:* is also distinct from integrations:write, which governs NexSpace platform webhook configuration and grants nothing here.
The credential’s bound user has an ACTIVE connection to that toolkit. In v1 the lane resolves the connections of the user the credential is bound to — the same set that user sees in the in-app assistant — and keeps only those whose status is active. Organization-owned connections (the social rails) stay in-app and never surface over MCP. An empty list usually means this user has connected nothing, even when colleagues have.

Tools are listed with the real parameter schema fetched from the broker. If that schema cannot be fetched, the tool is silently omitted rather than listed with a permissive placeholder shape — so a missing tool can mean a broker hiccup, not only a missing connection.

Dispatch

A tools/call for a connected-app tool re-checks the active connection first, before anything else runs. If the connection is gone you get a -32003 FORBIDDEN whose suggestion reads “Connect the app on the NexSpace Integrations page, then retry.” — refused up front, rather than parked as an approval row that could never execute. Past that gate the call runs the same governed path as a native NexSpace tool: org AI guardrails, idempotency, then scoped execution (suite entitlements, RBAC, AI rules, risk autonomy including the approval floor). A medium-plus-risk app action pauses for human approval exactly like a NexSpace write. Each successful brokered execution is additionally marked as a composio_execution outcome, so app calls are metered and attributable in usage analytics.

Discovering and managing connections

list_connected_apps enumerates the caller’s connections — toolkit slug, display name, status, connected-at. It is a read-only tool in the general category, so it is gated on general:read, not on any apps: scope: it works on a default read-only connector holding zero apps scopes, which is how an agent finds out what is connected before you grant apps:*.
Connecting and disconnecting is a human act on the NexSpace Integrations page. There is no tool for it, by design.

Getting Started

Core Concepts

Integrations

Reference

Composio

Composio Integration

Install

Connect

Available Tools

Example: LangChain Agent

API Key Fallback

Connected apps over MCP (inbound)

When a connected-app tool appears in `tools/list`

Dispatch

Discovering and managing connections

​Composio Integration

​Install

​Connect

​Available Tools

​Example: LangChain Agent

​API Key Fallback

​Connected apps over MCP (inbound)

​When a connected-app tool appears in tools/list

​Dispatch

​Discovering and managing connections

Composio Integration

Install

Connect

Available Tools

Example: LangChain Agent

API Key Fallback

Connected apps over MCP (inbound)

When a connected-app tool appears in `tools/list`

Dispatch

Discovering and managing connections