Machine surface

MCP server

Contextely speaks JSON-RPC 2.0 over the MCP Streamable HTTP transport at https://www.contextely.com/api/mcp. It is stateless: every call carries its own credential, so there is no session to resume and a dropped connection is a non-event.

Connect

{
  "mcpServers": {
    "contextely": {
      "url": "https://www.contextely.com/api/mcp",
      "headers": { "Authorization": "Bearer ctx_sk_..." }
    }
  }
}

Create a key under API keys in the dashboard. The key speaks as one member and is scored against that member's entitlement scopes.

Tools

context_search

counts against your retrieval allowance

The main call. Searches the workspace's condensed working memory and returns what this asker is entitled to see, refreshing anything past its freshness TTL from its system of record first.

REST equivalent: POST /api/v1/search

Arguments

query string (required): What you want to know, in natural language.
limit integer: 1-50, default 8.
skip_refresh boolean: Serve stored memory without a freshness check. Faster; may be stale.

context_related

Walk from one memory object to its neighbours, ranked by shared entities, then topics, then keywords. Use it when one search result is the right thread and you want the rest of it. A neighbour outside the asker's scopes is never named or counted.

REST equivalent: GET /api/v1/memory/{id}/related

Arguments

id string (required): The memory object to find neighbours of.
limit integer: 1-25, default 5.

context_expand

counts against your refresh allowance

Read the full current record from the system of record a memory object was condensed from, for when the summary is not enough. No model is involved, so it returns exactly what the source says. Costs one source round-trip, metered against the monthly refresh allowance.

REST equivalent: POST /api/v1/memory/{id}/expand

Arguments

id string (required): The memory object to expand.

memory_get

Fetch one memory object by id. Returns not_found rather than forbidden when the asker is not entitled to it, so probing for ids cannot reveal what exists.

REST equivalent: GET /api/v1/memory/{id}

Arguments

id string (required): Memory object id.

sources_list

List the connected systems of record with their freshness policies, sync status, and whether this asker is entitled to anything from each.

REST equivalent: GET /api/v1/sources

Arguments

(none)

workspace_usage

Plan, metered usage and remaining allowance for the month. Call it before a batch run to decide whether to proceed or back off.

REST equivalent: GET /api/v1/usage

Arguments

(none)

actions_list

The enabled actions the caller may invoke. Proposed and disabled actions never appear, and neither do actions whose required write scopes the caller does not hold.

REST equivalent: GET /api/v1/actions

Arguments

(none)

action_preview

Validates arguments and returns a rendered description plus the request hash, without contacting the source. It reports upstream_dry_run:false rather than simulating an effect, because a fabricated preview is indistinguishable from a real one.

REST equivalent: POST /api/v1/actions/{name}/preview

Arguments

name string (required): The action's name.
args string: The arguments, as an object.

action_invoke

counts against your refresh allowance

Performs one enabled action. Entitlement is checked at entry and again immediately before the effect; the allowance is charged only when it reaches upstream; and every attempt, refusals included, is recorded in the action log.

REST equivalent: POST /api/v1/actions/{name}/invoke

Arguments

name string (required): The action's name.
args string: The arguments, as an object.
idempotency_key string (required): Required. A server-generated key is not a replay guard.

What a search returns

{
  "query": "acme renewal date",
  "results": [
    {
      "id": "…",
      "title": "Acme renewal terms",
      "summary": "Acme renews 2027-01-31 at $48,000/yr…",
      "citation_url": "https://crm.internal/accounts/acme",
      "sourceName": "Production CRM",
      "score": 0.412,
      "matchedTerms": ["acme", "renewal"],
      "freshness": {
        "last_fetched_at": "2026-08-18T14:02:11Z",
        "ttl_seconds": 900,
        "state": "refreshed"
      }
    }
  ],
  "entitlement": {
    "asker": "priya@company.com",
    "role": "member",
    "scopes": ["sales"],
    "withheld_for_entitlement": 2
  },
  "freshness": { "refreshed": 1, "refresh_failed": 0 }
}

Read withheld_for_entitlement. When it is above zero, relevant context existed that this asker may not see. A well-behaved agent says so, with “there may be more here that needs finance access”, rather than answering confidently from a partial picture.

Read freshness.state. fresh and refreshed mean the fact was verified within its TTL. stale_refresh_failed means it could not be verified, and the attached warning says why.

Errors

A tool that fails for a caller-fixable reason returns a normal tool result with isError: true and a machine-readable code, so an agent can branch rather than parse prose. quota_exceeded means back off or upgrade; not_found means never retry. An invalid credential is a transport-level JSON-RPC error.