> ## Documentation Index
> Fetch the complete documentation index at: https://docs.melso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Melso product MCP: https://melso.ai/api/mcp (OAuth; one company per grant). REST: https://melso.ai. Documentation-search MCP: https://docs.melso.ai/mcp. The docs search server does not act on customer accounts.
>
> Use the live tool schema and respect company membership. Ask the person to authorize the exact fiscal document version in the signed-in app. A professional prepares and files included returns after authorization; AI does not file alone. A prepared file or approval receipt is not evidence of filing. Never claim completion from an accepted Task or Run. Keep credentials out of chat and logs. Agents features are internal or by private invitation.

# Connect Melso MCP

> Authorize a remote MCP client for one Melso company.

<Steps>
  <Step title="Choose your client">
    Use [Claude](/mcp/claude), [ChatGPT](/mcp/chatgpt), [Cursor](/mcp/cursor), or another client that supports remote MCP over Streamable HTTP and OAuth.
  </Step>

  <Step title="Add the product endpoint">
    Enter `https://melso.ai/api/mcp`. Do not paste a REST API key or personal token into the connection.
  </Step>

  <Step title="Sign in and choose a company">
    Complete Melso’s OAuth screen. Review the company and requested access before authorizing. Each connection is bound to the company chosen at consent.
  </Step>

  <Step title="Read the available tools">
    Ask the client to list Melso tools, then read company context with `workspace_status`. Tool visibility can vary with company type, plan, membership and connected services.
  </Step>
</Steps>

## Reconnect or change access

If authentication expires, let the client refresh its OAuth token or reconnect. To work with a different company, authorize a connection for that company; a tool argument cannot switch an existing grant’s company.

A `401` can mean you used the wrong credential type. A `403` can mean company membership or tool access changed. Reconnecting does not grant permissions that your Melso account lacks.

## Try a first read

After consent, ask your client: **“Read my Melso company context without changing anything.”** The client lists tools and calls [`workspace_status`](/mcp/tools/workspace-status) with `{"include":["company"]}`. The `include` field is optional; specifying it limits this first read to company context. Successful sections appear by name. The `errors` object appears only when a requested section could not be read.

For a custom client, initialize with the supported `2025-11-25` protocol version for this example and use the `access_token` from the `/oauth/token` response in [Token exchange](/mcp/oauth#token-exchange). The following Bash subshell disables tracing, reads the token without echoing or exporting it, and sends the header through standard input. Do not use a REST key or add a company header:

```bash theme={null}
(
set +x
set -euo pipefail
unset MELSO_MCP_TOKEN
trap 'unset MELSO_MCP_TOKEN' EXIT
if ! IFS= read -r -s -p 'MCP OAuth access token: ' MELSO_MCP_TOKEN || [[ -z "$MELSO_MCP_TOKEN" ]]; then
  printf '\nAn MCP OAuth access token is required.\n' >&2
  exit 1
fi
printf '\n'
mcp() {
  printf 'Authorization: Bearer %s\n' "$MELSO_MCP_TOKEN" | \
  curl --fail-with-body -sS https://melso.ai/api/mcp \
    --header @- \
    -H 'MCP-Protocol-Version: 2025-11-25' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    --data-binary "$1"
}
# 1. Handshake: initialize, then the initialized notification (202, no body).
mcp '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"melso-docs-example","version":"1.0.0"}}}'
printf '\n'
mcp '{"jsonrpc":"2.0","method":"notifications/initialized"}'
# 2. The first read.
mcp '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"workspace_status","arguments":{"include":["company"]}}}'
)
```

The example performs the standard MCP handshake (`initialize`, then `notifications/initialized`) before the first `tools/call`, as every MCP client does. Include the negotiated `MCP-Protocol-Version` header on every request. A successful JSON-RPC envelope has `result`; tools return MCP content blocks and may also include `structuredContent`. For example, this success envelope is trimmed to the company name and kind:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{"type": "text", "text": "{\"company\":{\"name\":\"Example business\",\"kind\":\"freelancer\"}}"}],
    "structuredContent": {"company": {"name": "Example business", "kind": "freelancer"}}
  }
}
```

There is no `errors` field when every requested section succeeds. If the company read fails, the decoded payload can instead be:

```json theme={null}
{"errors":{"company":"company_get could not read platform capabilities"}}
```

Section errors map names to error strings; successful sections remain alongside them when you request more than one. Check for a JSON-RPC `error`, `result.isError` and these section errors before relying on a read. See the [workspace\_status contract](/mcp/tools/workspace-status) and [result handling](/mcp/results). A `401` requires the correct OAuth flow; a `403` requires checking company access. Use a secret manager for a deployed client.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.