MCP Tools
Context & Resources

add_context

Add a new reference item to your context library, the source material that powers on-brand AI generation. Supply the body as pasted markdown, a one-off URL import, a tracked live web page, or calls imported from a connected call-recording app, and optionally file it under a collection or project.

Parameters

NameTypeRequiredDefaultDescription
namestringYes—Short, descriptive label for this reference item, shown in the library list and used when the AI cites it — make it specific enough to tell similar items apart ("Q3 Pricing Page" rather than "Pricing"). Required. When tracking a live web page, an empty name falls back to the page's own title.
contentstringNo—The item's body as markdown, pasted inline. Best for short or hand-authored material — it is stored as-is and embedded for retrieval immediately, so the item is usable the moment the call returns. Exactly one of content, import_url, or connected_webpage_url must be set; sending none, or more than one, is rejected (an empty string counts as not set).
import_urlstringNo—A publicly reachable URL to fetch ONCE and store as a static markdown snapshot; the page is imported once as a static snapshot that cannot be refreshed (use connected_webpage_url for a page that should stay current). Use it for one-off material — a competitor's post, an exported doc behind a temporary link. Exactly one of content, import_url, or connected_webpage_url may be set (none or two-plus is rejected), and the call waits up to about 25 seconds for the import: import_status "ready" on success, an error if the page can't be read (nothing is added), or "processing" only for a slow page. In that case the item does not exist until the import finishes: poll get_context_item with the returned id for up to about 5 minutes (not found, then the item with its content); if it is still not found, tell the user the save couldn't be confirmed yet and do not re-add the URL yourself. A failed slow import sends the user a "wasn't saved" notification.
connected_webpage_urlstringNo—A URL to track as a live page: the page is fetched and its URL is stored, so the item can be re-pulled later with update_context refresh_webpage. Use it for the customer's own pages and anything you want to keep current; re-adding a URL the team already tracks updates that item in place rather than creating a duplicate, and its stored content is overwritten with the fresh fetch. Because of that overwrite, add_context is marked as a destructive tool. Exactly one of content, import_url, or connected_webpage_url may be set (none or two-plus is rejected), and adding a tracked page requires an admin or editor role. The call waits up to about 25 seconds for the page, the same way import_url does: import_status "ready" on success, an error on failure (nothing is added for a new URL, and a tracked URL keeps its saved copy), or "processing" only if it is slow. In that case the item exists at once with empty content (word_count 0) until the fetch lands: poll get_context_item for up to about 5 minutes (a failed new page is removed, so it comes back not found; a tracked page keeps its saved copy); if unconfirmed, tell the user and do not re-add the URL.
collection_idinteger | nullNo—Numeric ID of the collection to file this item in, from list_context_collections or create_context_collection. Omit it (or pass null or 0) to leave the item loose in the reference library. The collection must belong to your team, and a private collection must be one you created — otherwise the call is rejected.
project_idstringNo—UUID of a project to attach this item to, from list_projects, so it shows up as that project's reference material. Omit it to leave the item unattached to any project. The project must belong to your team or the call fails, and users with the collaborator role can only add reference material inside a project, so for them this is effectively required.
as_callbooleanNo—Whether to save `content` as a call transcript in Calls. Omit it and Marcora decides: text that looks like a transcript becomes a call. true: save as a call even if it does not look like one. false: save as an ordinary context item even if it looks like a transcript. Only valid with `content`.
audiencestringNo—Calls only. Who can see the call: only_me (default; visible only to the person who added it) or team. Rejected when the text is saved as an ordinary context item.
call_datestringNo—Calls only. When the call happened, as YYYY-MM-DD or an ISO 8601 timestamp. Omit it to take the date from the transcript.
call_kindstringNo—Calls only. The kind of call: customer (a customer call), external (a meeting with people outside the team), team_meeting, one_on_one, recorded (a recorded talk or other single-speaker recording). Omit it to let Marcora work it out from who spoke.
call_companystringNo—Calls only. The other company on the call (null for none). Omit it to take the company from the transcript.
import_fromobjectNo—Bring in calls from a connected call-recording app instead of passing text. Use it instead of content, import_url and connected_webpage_url (it cannot be combined with them or with as_call, call_date, call_kind or call_company). Marcora fetches and cleans the transcripts itself; never pass transcript text. audience, project_id and collection_id apply as for calls. Fields: toolkit (fathom, gong or fireflies) and call_ids (the app's own call ids, 1 to 10, each once).

Input Schema

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "Short, descriptive label for this reference item, shown in the library list and used when the AI cites it — make it specific enough to tell similar items apart (\"Q3 Pricing Page\" rather than \"Pricing\"). Required. When tracking a live web page, an empty name falls back to the page's own title."
    },
    "as_call": {
      "type": "boolean",
      "description": "Whether to save `content` as a call transcript in Calls. Omit it and Marcora decides: text that looks like a transcript becomes a call. true: save as a call even if it does not look like one. false: save as an ordinary context item even if it looks like a transcript. Only valid with `content`."
    },
    "content": {
      "type": "string",
      "description": "The item's body as markdown, pasted inline. Best for short or hand-authored material — it is stored as-is and embedded for retrieval immediately, so the item is usable the moment the call returns. Exactly one of content, import_url, or connected_webpage_url must be set; sending none, or more than one, is rejected (an empty string counts as not set)."
    },
    "audience": {
      "enum": [
        "only_me",
        "team"
      ],
      "type": "string",
      "description": "Calls only. Who can see the call: only_me (default; visible only to the person who added it) or team. Rejected when the text is saved as an ordinary context item."
    },
    "call_date": {
      "type": "string",
      "description": "Calls only. When the call happened, as YYYY-MM-DD or an ISO 8601 timestamp. Omit it to take the date from the transcript."
    },
    "call_kind": {
      "enum": [
        "customer",
        "external",
        "team_meeting",
        "one_on_one",
        "recorded"
      ],
      "type": "string",
      "description": "Calls only. The kind of call: customer (a customer call), external (a meeting with people outside the team), team_meeting, one_on_one, recorded (a recorded talk or other single-speaker recording). Omit it to let Marcora work it out from who spoke."
    },
    "import_url": {
      "type": "string",
      "description": "A publicly reachable URL to fetch ONCE and store as a static markdown snapshot; the page is imported once as a static snapshot that cannot be refreshed (use connected_webpage_url for a page that should stay current). Use it for one-off material — a competitor's post, an exported doc behind a temporary link. Exactly one of content, import_url, or connected_webpage_url may be set (none or two-plus is rejected), and the call waits up to about 25 seconds for the import: import_status \"ready\" on success, an error if the page can't be read (nothing is added), or \"processing\" only for a slow page. In that case the item does not exist until the import finishes: poll get_context_item with the returned id for up to about 5 minutes (not found, then the item with its content); if it is still not found, tell the user the save couldn't be confirmed yet and do not re-add the URL yourself. A failed slow import sends the user a \"wasn't saved\" notification."
    },
    "project_id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of a project to attach this item to, from list_projects, so it shows up as that project's reference material. Omit it to leave the item unattached to any project. The project must belong to your team or the call fails, and users with the collaborator role can only add reference material inside a project, so for them this is effectively required."
    },
    "import_from": {
      "type": "object",
      "required": [
        "toolkit",
        "call_ids"
      ],
      "properties": {
        "toolkit": {
          "type": "string",
          "description": "fathom, gong or fireflies."
        },
        "call_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 10,
          "minItems": 1,
          "description": "The app's own call ids, 1 to 10, each once. Get them from its list or search tool."
        }
      },
      "description": "Bring in calls from a connected call-recording app instead of passing text. Use it instead of content, import_url and connected_webpage_url (it cannot be combined with them or with as_call, call_date, call_kind or call_company). Marcora fetches and cleans the transcripts itself; never pass transcript text. audience, project_id and collection_id apply as for calls."
    },
    "call_company": {
      "type": [
        "string",
        "null"
      ],
      "description": "Calls only. The other company on the call (null for none). Omit it to take the company from the transcript."
    },
    "collection_id": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Numeric ID of the collection to file this item in, from list_context_collections or create_context_collection. Omit it (or pass null or 0) to leave the item loose in the reference library. The collection must belong to your team, and a private collection must be one you created — otherwise the call is rejected."
    },
    "connected_webpage_url": {
      "type": "string",
      "description": "A URL to track as a live page: the page is fetched and its URL is stored, so the item can be re-pulled later with update_context refresh_webpage. Use it for the customer's own pages and anything you want to keep current; re-adding a URL the team already tracks updates that item in place rather than creating a duplicate, and its stored content is overwritten with the fresh fetch. Because of that overwrite, add_context is marked as a destructive tool. Exactly one of content, import_url, or connected_webpage_url may be set (none or two-plus is rejected), and adding a tracked page requires an admin or editor role. The call waits up to about 25 seconds for the page, the same way import_url does: import_status \"ready\" on success, an error on failure (nothing is added for a new URL, and a tracked URL keeps its saved copy), or \"processing\" only if it is slow. In that case the item exists at once with empty content (word_count 0) until the fetch lands: poll get_context_item for up to about 5 minutes (a failed new page is removed, so it comes back not found; a tracked page keeps its saved copy); if unconfirmed, tell the user and do not re-add the URL."
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Context item ID"
    },
    "call": {
      "type": "object",
      "required": [
        "audience"
      ],
      "properties": {
        "date": {
          "type": [
            "string",
            "null"
          ],
          "description": "When it happened (ISO 8601), or null."
        },
        "kind": {
          "enum": [
            "customer",
            "external",
            "team_meeting",
            "one_on_one",
            "recorded",
            null
          ],
          "type": [
            "string",
            "null"
          ],
          "description": "Kind of call."
        },
        "people": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "name",
              "side"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "side": {
                "enum": [
                  "internal",
                  "external",
                  "unknown"
                ],
                "type": "string",
                "description": "internal = user’s team."
              },
              "company": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "description": "Who was on the call."
        },
        "company": {
          "type": [
            "string",
            "null"
          ],
          "description": "Other company, or null."
        },
        "audience": {
          "enum": [
            "only_me",
            "team"
          ],
          "type": "string",
          "description": "only_me or team."
        },
        "summary_status": {
          "enum": [
            "pending",
            "ready",
            "skipped",
            "failed",
            "waiting_credits",
            null
          ],
          "type": [
            "string",
            "null"
          ],
          "description": "Summary state; ready = a summary exists."
        }
      },
      "description": "Call details; present only on call items."
    },
    "name": {
      "type": "string",
      "description": "Context item name"
    },
    "content": {
      "type": [
        "string",
        "null"
      ],
      "description": "Always null on add_context for URL paths and pasted content — fetch the body with get_context_item"
    },
    "message": {
      "type": "string",
      "description": "Calls only. Where it went and who can see it; tell the user."
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "call_id",
          "status",
          "message"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The context item's name (imported)."
          },
          "status": {
            "enum": [
              "imported",
              "duplicate",
              "not_ready",
              "failed"
            ],
            "type": "string",
            "description": "imported = saved; duplicate = already in Marcora; not_ready = the app has no transcript yet, try later; failed = it could not be brought in."
          },
          "call_id": {
            "type": "string",
            "description": "The app's id for the call."
          },
          "message": {
            "type": "string",
            "description": "What happened, in words for the user."
          },
          "audience": {
            "enum": [
              "only_me",
              "team"
            ],
            "type": "string",
            "description": "Who can see it (imported)."
          },
          "filed_in": {
            "type": "string",
            "description": "Where it was filed, in words: Calls, a project or a collection (imported)."
          },
          "link_url": {
            "type": "string",
            "description": "Opens the context item in the Marcora web app (imported). Present exactly as returned."
          },
          "context_item_id": {
            "type": "string",
            "format": "uuid",
            "description": "The saved context item (imported), or the existing one (duplicate)."
          }
        }
      },
      "description": "Present only on an import_from add: one entry per requested call, in order."
    },
    "summary": {
      "type": "object",
      "required": [
        "imported",
        "duplicate",
        "not_ready",
        "failed"
      ],
      "properties": {
        "failed": {
          "type": "integer"
        },
        "imported": {
          "type": "integer"
        },
        "duplicate": {
          "type": "integer"
        },
        "not_ready": {
          "type": "integer"
        }
      },
      "description": "Present only on an import_from add: how many calls ended in each state."
    },
    "audience": {
      "enum": [
        "only_me",
        "team"
      ],
      "type": "string",
      "description": "Calls only. Who can see it."
    },
    "capacity": {
      "type": "object",
      "properties": {
        "used": {
          "type": "integer"
        },
        "limit": {
          "type": "integer"
        },
        "remaining": {
          "type": "integer"
        }
      },
      "description": "Present only when the team's plan limits context items: {used, limit, remaining} after this add. Absent when the plan has no limit. At the limit, a call that would create an item returns an error stating the limit"
    },
    "link_url": {
      "type": "string",
      "description": "URL to view this context item in the Marcora web app."
    },
    "created_at": {
      "type": "integer",
      "description": "Unix timestamp of creation"
    },
    "project_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Project association (if assigned)"
    },
    "word_count": {
      "type": "integer",
      "description": "Word count of content (0 while an import is still processing)"
    },
    "import_from": {
      "type": "object",
      "required": [
        "toolkit",
        "app_name"
      ],
      "properties": {
        "toolkit": {
          "type": "string",
          "description": "The app's id, for example fathom."
        },
        "app_name": {
          "type": "string",
          "description": "The app's name to show the user."
        }
      },
      "description": "Present only on an import_from add: which app the calls came from."
    },
    "content_type": {
      "type": "string",
      "description": "manual (content/import_url) or webpage (connected_webpage_url)"
    },
    "collection_id": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Collection this item belongs to (if assigned)"
    },
    "import_status": {
      "type": [
        "string",
        "null"
      ],
      "description": "For import_url and connected_webpage_url items: \"ready\" once the page has loaded (the call waits up to ~25 seconds); \"processing\" only if it is still running. null for pasted content"
    },
    "saved_as_call": {
      "type": "boolean",
      "description": "True when saved as a call."
    },
    "automatic_import_link": {
      "type": "string",
      "description": "Present only when at least one call was imported. Opens the automatic-import rule editor with this source, destination and audience filled in; nothing is saved until the user saves it. Offer it, exactly as returned."
    },
    "brand_foundation_build": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "description": "Always \"queued\" on add_context"
        },
        "message": {
          "type": "string",
          "description": "What to tell the user"
        }
      },
      "description": "Present only on a connected_webpage_url add that queued a build of the team's blank Brand Foundation sections from the website: {status: \"queued\", message}. message says what to tell the user (the blank sections are being built and should be ready within about a minute, not empty). Absent otherwise, so never imply a build is running without it"
    }
  }
}

Instructions

Use this tool to add a new context item to your reference library.

Workflow:

  1. Provide a descriptive name.
  2. Provide exactly one body source: content (markdown directly), import_url (a public URL imported once as a static snapshot), or connected_webpage_url (a public URL tracked as a live, refreshable web page). connected_webpage_url requires admin or editor role. To bring in calls from a connected call-recording app instead, use import_from (see Importing calls from a connected app below).
  3. Optionally assign to a collection by passing collection_id. Use list_context_collections to see existing collections and their IDs, or use create_context_collection to create a new one and get its ID. Omit it — or pass 0 — to file the item at the top level of the Reference Library.
  4. Optionally associate with a project by passing project_id. Use list_projects to see available projects and their IDs. Omit it to leave the item unassociated.

Filing an item in the Reference Library: omitting collection_id — or passing 0 — files the item at the top level of the Reference Library, where it's returned by list_context_items, fetchable via get_context_item, and eligible for semantic search. This is the normal path for team-wide reference material.

Unlike update_context, this tool's collection_id is typed as a bare integer in the input schema, so a strict MCP client cannot send a literal null here. You don't need one: collection_id is optional on add_context, so simply omitting it is the idiomatic way to file at the top level. (The server treats an explicit null the same as omitted/0, but only clients that don't validate against the schema can send it.)

import_url: The call waits for the import, up to about 25 seconds. If the page loads in that time, it returns the new item's id with import_status: "ready" (the body is not in this response; get_context_item returns it). If the page can't be read, it returns an error and nothing is added; the error says why. Only a slow page returns import_status: "processing", with a real item id; the content lands a moment later.

connected_webpage_url: The call waits up to about 25 seconds for the page, the same way import_url does: import_status: "ready" on success. If the page can't be read it returns an error: nothing is added for a new URL, and a page the team already tracks keeps its saved copy. Only a slow page returns import_status: "processing".

After "processing": get_context_item does not return import_status, so poll it with the returned id for up to about 5 minutes.

  • import_url: the item is not found until the import finishes, then it returns the item with its content.
  • connected_webpage_url: the item exists at once with empty content (word_count 0) until the fetch lands. If a new page's fetch fails, the item is removed (not found); a tracked page keeps its saved copy.
  • If it is still unconfirmed after about 5 minutes, tell the user the import couldn't be confirmed yet. Do not re-add the URL: a retry can create a duplicate.
  • A slow import_url that fails sends the user a "wasn't saved" notification.

Plan capacity: when the team's plan limits context items, the result includes capacity ({used, limit, remaining}); it is absent on an unlimited plan. At the limit, a call that would create an item (content, import_url, or a new web page) returns an error stating the limit; deleting an item makes room. Re-adding a connected_webpage_url the team already tracks still refreshes it. A processing import_url counts in that reply but does not reserve the slot: if another add fills it, the import is refused when it finishes and adds nothing. A new web page holds its slot from the start.

Output: content in the add result is always null for URL paths and pasted content; fetch the body with get_context_item.

Brand Foundation build: a connected_webpage_url add that queued a build of the team's blank Brand Foundation sections from the website also returns brand_foundation_build: {status: "queued", message}. message says what to tell the user: the blank sections are being built and should be ready within about a minute, not empty. Absent otherwise, so never imply a build is running without it.

Calls: text that looks like a call transcript (WebVTT or SRT, or lines with speaker labels and timestamps) is saved as a call in Calls, and the result says so (saved_as_call: true). Pass as_call: true to save any text as a call, or as_call: false to keep it an ordinary context item. A call is Only me (visible only to the person who added it) unless you pass audience: "team"; ask the user if you are unsure who should see it. Optional call details: call_date (ISO 8601), call_kind, call_company; anything left out is worked out from the transcript. A call takes content only, and audience, call_date, call_kind and call_company apply to calls only: sending one for text saved as an ordinary context item is rejected rather than ignored. The summary is written after the save; call.summary_status shows where it is, and get_context_item returns the summary once ready.

Importing calls from a connected app: a fourth way, import_from: { toolkit, call_ids }, brings in calls the user keeps in a call-recording app. Use it instead of content, import_url and connected_webpage_url, and without as_call, call_date, call_kind or call_company.

  1. Find out whether the app is connected with find_app; it also returns the Connect link if it is not.
  2. Find the calls with the app's own list or search tool in your session, then pass their ids (1 to 10) in this ONE call. toolkit is fathom, gong or fireflies.
  3. Marcora fetches and cleans each transcript itself through the user's own connection, so never retype or paste a transcript. Transcript text is never returned in the result.

audience, project_id and collection_id work as they do for calls: Only me and filed in Calls unless you say otherwise. A Collaborator must pass project_id; choose one of project_id or collection_id. name is ignored here, because each call keeps its own title.

Import result: import_from ({toolkit, app_name}), results[] with one entry per requested call in the order you sent them, and summary with the counts. Each result has a status:

  • imported: saved. The row carries context_item_id, name, audience, filed_in and link_url.
  • duplicate: already in Marcora; the row carries the existing context_item_id.
  • not_ready: the app has no transcript for that call yet. Try again later.
  • failed: it could not be brought in, with a message for the user. A bad connection on one call stays in its own row while the later calls continue. If the team's plan has no room for another call, the row is a failed row with the plan's limit message.

If the app is not connected, the whole call fails with an error that names the app and carries its Connect link: give the user that link, and retry once they have connected. When at least one call was imported, the result also carries automatic_import_link: offer it so the user can set up automatic import. It opens the rule editor with these choices filled in, and nothing is saved until the user saves it.

Use context items for: brand voice guidelines, company facts, product descriptions, audience personas, competitive intelligence.

Errors

  • 400 — exactly one of content, import_url, or connected_webpage_url is required (none, or more than one, was supplied)
  • 400 — import_url or connected_webpage_url could not be fetched or parsed (check the URL is publicly reachable); nothing is added
  • 403 — connected_webpage_url requires admin or editor role
  • 400 — import_from cannot be combined with content, import_url, connected_webpage_url, as_call, call_date, call_kind or call_company; toolkit must be fathom, gong or fireflies, with 1 to 10 call_ids
  • Not connected — an error naming the app, with its Connect link
  • At the plan's limit — an error stating the limit; deleting an item makes room

Example prompts

  • "Add our brand guidelines to Marcora"
  • "Store this competitive analysis as context"
  • "Import https://example.com/competitor-pricing as a one-off snapshot called 'Acme pricing'"
  • "Track our pricing page (https://example.com/pricing) as a web page so I can refresh it later"
  • "Add this product brief to the 'Product Launch' collection"

Links: present link_url to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

Examples

Add competitor research to a project

Store competitor analysis as context tied to a specific project, so content generated for that project can reference competitive positioning.

Input
{
  "name": "Q2 Competitor Analysis — Acme Corp",
  "content": "Acme Corp launched a freemium tier in March. Their messaging focuses on speed and simplicity. Key weakness: no enterprise SSO support.",
  "project_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
Output
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "name": "Q2 Competitor Analysis — Acme Corp",
  "content": "Acme Corp launched a freemium tier in March...",
  "word_count": 27,
  "project_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "created_at": 1712678400
}

Import calls from a connected app

Bring two calls from the user's Gong account into Marcora as Only me calls. Marcora fetches the transcripts itself; none is returned.

Input
{
  "import_from": {
    "toolkit": "gong",
    "call_ids": [
      "7782342274025937895",
      "7782342274025937901"
    ]
  }
}
Output
{
  "import_from": {
    "toolkit": "gong",
    "app_name": "Gong"
  },
  "results": [
    {
      "call_id": "7782342274025937895",
      "status": "imported",
      "message": "Imported.",
      "context_item_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "name": "Acme renewal call",
      "audience": "only_me",
      "filed_in": "Calls",
      "link_url": "https://app.marcora.ai/..."
    },
    {
      "call_id": "7782342274025937901",
      "status": "not_ready",
      "message": "Gong has no transcript for this call yet. Try again later."
    }
  ],
  "summary": {
    "imported": 1,
    "duplicate": 0,
    "not_ready": 1,
    "failed": 0
  },
  "automatic_import_link": "https://app.marcora.ai/..."
}
Scroll to Top