Machine-to-machine integration

Building an AI agent or assistant workflow? Use MCP. Syncing data or building a system integration? Use the REST API and the Solibo Home SDK, starting at Getting started on the developer portal; Concepts explains housing communities, sections, residents and roles. Credentials for both: solibohome@solibo.no.

Connect your service or automation directly to Solibo Home MCP without an interactive sign-in. Email solibohome@solibo.no for a client ID and client secret. The board of each housing community (API: company) approves your access, and Solibo then grants your client that community and the scopes your integration needs.

Get an access token

Request a token using your provisioned credentials:

curl -sS https://auth.home.solibo.no/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \
  --data-urlencode "scope=solibo.mcp/read"

Use the returned access_token as a bearer token. Keep credentials and tokens in your service’s secure configuration.

Call the MCP server

Use an MCP client with Streamable HTTP and bearer-token support, or follow this request sequence. Replace the placeholders with your token and session ID.

First, initialize the connection:

curl -sS -i https://mcp.home.solibo.no \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "my-service", "version": "1.0"}
    }
  }'

Reuse the returned Mcp-Session-Id header on subsequent requests. Complete initialization:

curl -sS https://mcp.home.solibo.no \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

Then discover the tools available to your integration:

curl -sS https://mcp.home.solibo.no \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

Make your first tool call

Use tools/call with a tool name and arguments from its returned schema. For an account-data workflow, begin by loading the session context:

curl -sS https://mcp.home.solibo.no \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 3, "method": "tools/call",
    "params": {"name": "initialize_session_context", "arguments": {}}
  }'

The result provides the accessible company context for subsequent queries. Use IDs from returned records when calling other tools, and follow each tool’s input schema. Reusing the session also preserves session shortcuts.

For a first integration, start with a read-only workflow such as a company briefing or an overdue-task report.

How the tools behave

Planning hints. Pass the instructions from the initialize response to your agent; they carry routing, confirmation and privacy rules. In tools/list, each tool names its scope in securitySchemes and its planning hints in _meta.solibo. Compare those scopes with the ones granted to your client; list_user_actions reports a signed-in person’s permissions and does not work for a machine client. The backend still decides. Data comes back mostly in Norwegian; get_board_report takes responseLanguage, for example en.

Working company. Single-company tools default to the company set with set_working_company. It lapses two hours after the session’s company selection was last changed, so set it at the start of each run. Company scope is a separate, broader selection; clearing one does not clear the other.

Paging and completeness. Check complete, any *Coverage object and any *Truncated flag before you treat a result as complete. Page with paging.next as pageToken until it is absent; a list with no more pages has no next. A missing value or an empty result is never the same as zero.

Dates. A date-only filter (YYYY-MM-DD) is a Europe/Oslo calendar day, and both ends of a range are inclusive. Timestamps with an explicit offset and epoch milliseconds are exact. An invalid date, or a range whose start is after its end, is a validation error; the filter is never dropped silently.

Time limits. A read, a preview, an audited reveal or a confirmed change must finish within 175 s. A read that times out changed nothing; narrow it and try again. The service retries a failed read at most twice and does not resend a change after a server error or timeout. If Solibo Home cannot be reached to admit your token, the endpoint answers HTTP 503 temporarily_unavailable with Retry-After; retry rather than signing in again.

Sensitive values. Normal tools mask financial identifiers and filter personal contact details. The reveal_* tools return full values or text for one narrow purpose, and every call is audited.

Changes and messages

Write and communication tools change nothing by themselves. They return a preview whose _meta.pendingAction carries previewId, the confirmTool to call and expiresAtEpochSeconds. Within 12 hours, call that tool with only {"previewId": "PREVIEW_ID", "confirmed": true}. The change was applied only when _meta.pendingAction.status is EXECUTED; a dry run or a denial saves nothing. If Solibo Home refuses the change (for example 400, 403, 404, 409, 422 or 429), or the call fails before anything is sent, nothing was changed and the pending action stays open: fix the cause, then confirm again or preview a corrected change. If _meta.outcomeUnknown is true, the change may or may not have been applied; do not repeat the call, and check Solibo Home first.

To create the same record in several housing communities, call the matching create_*_for_companies tool (create_feed_posts_for_companies, create_practical_info_for_companies, create_issues_for_companies, create_tasks_for_companies, create_conversations_for_companies or create_meetings_for_companies). Its preview is the pending action you confirm. For a newsletter to several housing communities, prepare_batch_newsletter first returns a batch preview that lasts 30 minutes; pass its previewId to draft_batch_newsletter to get the pending action you confirm.

The customer message tools (draft_customer_message, send_customer_message) are for email and SMS to owners, tenants, the board and others in a housing community, and need solibo.mcp/communicate.

Scopes and permissions

Scope Purpose
solibo.mcp/read Read tools available to your integration
solibo.mcp/write Confirmed changes, when provisioned
solibo.mcp/communicate Confirmed communications, when provisioned

Request only the scopes you need. Solibo Home access restrictions and the preview and confirmation flow still apply; see Changes and messages.

Solibo AS