# Authentication Source: https://developers.within.ai/authentication OAuth where the client supports it, API key everywhere else. The Within MCP supports two authentication methods. Most clients will use one or the other based on what they support. | Method | When to use | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **OAuth** | Preferred. Use in any client that supports MCP OAuth (Claude, ChatGPT, Claude Code via the plugin, Codex via `codex mcp login`, Cursor via the **Connect** button, Gemini CLI via `/mcp auth`). | | **API key** | Use when you need a long-lived headless connection, or for custom and automated setups where the OAuth flow isn't a fit. | Both methods scope the assistant to your active Within workspace and obey the same permissions as your Within user account. ## Enable the MCP in your workspace Whichever auth method your client uses, the very first step is to turn the MCP on for the workspace you want to expose. Sign-in and Bearer-token connections will both fail until this is done. Sign in to your Within workspace in a browser. Go to **Settings → MCP**. Select the workspace you want your assistant to read from. This is the workspace the MCP will be enabled for. Follow the in-app prompts to finish enabling the MCP. Once that's done, return to your AI client and continue with the install steps for it. If you try to sign in (OAuth) or send a Bearer token before completing the workspace setup, the request will fail. This is the most common cause of "auth failed" errors. See [FAQ](/faq) for other common install issues. ## OAuth When the client supports MCP OAuth, you don't handle any credentials yourself. The first time the assistant calls a Within tool, the client redirects you to sign in to Within. After that, the client manages the token. Per-client setup is covered in the [Install pages](/install/claude). Your organization may need to approve the Within connector or app before users can sign in. Contact your Within workspace admin if the OAuth redirect fails. ## API key API key auth uses a long-lived secret that you generate in Within and pass to the MCP server as a `Bearer` token. Use this for any custom or headless setup, or when a client doesn't yet support MCP OAuth. ### Generate a key Make sure you've completed [Enable the MCP in your workspace](#enable-the-mcp-in-your-workspace) first — keys are scoped to the workspace you selected there. Go to **Settings → MCP** in the workspace you enabled. Name it after the client you're connecting (e.g., `Claude Code – laptop`, `Cursor – work`). Set an expiration and click **Create**. The full key is shown once. If you lose it, you'll need to generate a new one. You can view, disable, or rotate existing keys from the same screen. Keys are bound to the workspace they were generated in — to work in a different workspace, generate a separate key there (see [Switching workspaces](#switching-workspaces)). ### Pass the key to your client Each client expects the key in a different place. The full request always carries: ```text theme={null} Authorization: Bearer ``` Per-client snippets: * [Claude Code](/install/claude-code#manual-mcp-add-api-key) * [Codex](/install/codex#config-file-install-api-key) * [Cursor](/install/cursor) * [Gemini CLI](/install/gemini-cli#api-key-fallback) * [GitHub Copilot](/install/github-copilot#api-key-install) ### Keep keys safe Anyone with your API key can read everything your Within user can read. Don't commit keys to git, share them in chat, or check them into shared configs. Prefer environment variables over inline values in JSON/TOML files, and rotate immediately if a key is exposed. ## Switching workspaces Each connection is scoped to a single Within workspace. If you belong to more than one, how you switch depends on your authentication method. ### OAuth Disconnect the Within connection in your client and reconnect. The reconnect flow shows a workspace picker, so you choose the workspace at sign-in. ### API key API keys are bound to the workspace they were generated in — an existing key cannot be pointed at a different workspace. If you haven't already, complete [Enable the MCP in your workspace](#enable-the-mcp-in-your-workspace) for the workspace you want to switch to. In that workspace, go to **Settings → MCP** and create a new API key. Update your client to send the new key as the `Bearer` token. The connection now reads from the new workspace. # Artifacts Source: https://developers.within.ai/concepts/artifacts The source documents and recordings behind processes — the underlying evidence the workspace captured. **Artifacts** are the source documents and recordings behind processes: BRDs, SOPs, video recordings, screenshots, audio, diagrams, logs. Anything the workspace captured. Use artifacts when the user wants to cite a specific document, replay a session, or read the underlying source. | User question | Tool to start with | | ------------------------------- | ------------------------------------------------------------------------- | | "Find the latest SOX checklist" | [`search_artifacts`](/tools/artifacts) | | "Show me the full text" | [`get_artifact_content`](/tools/artifacts) | | "Cite specific lines" | [`get_artifact_content`](/tools/artifacts) with `start_line` / `end_line` | ## Always follow up search with content `search_artifacts` returns short snippets to help you locate the right artifact. Always chain into `get_artifact_content` (full text, or a `start_line`/`end_line` range) to read the full passage before answering. Snippets are not citations. See [Tools by purpose → Artifacts](/tools/artifacts) for the full toolset. # Discover → Structure → Improve Source: https://developers.within.ai/concepts/discover-structure-improve How Within captures, organizes, and improves how your organization runs. Within runs the **Discover → Structure → Improve** loop continuously, replacing one-time "transformation projects" that take months and have a low success rate. When your agent uses the MCP, it's plugging into that loop. ```mermaid theme={null} flowchart LR D[Discover] --> S[Structure] --> I[Improve] --> D ``` ## Discover The Companion (ambient capture from sessions) and the Interviewer (AI-guided structured capture) generate raw process knowledge from how work actually happens. Agents read this layer through process, observation, and artifact tools. What lives here: * Observations from real sessions (deviations, exceptions, manual workarounds) * Source artifacts (BRDs, SOPs, video recordings, screenshots, logs) * Activity timelines that show the exact sequence of user actions ## Structure The [Process Index](/concepts/process-index) is Within's context graph of how your organization runs — a living, queryable map of every process, its dependencies, and the evidence captured against it. Agents navigate this layer through `search`, `fetch`, and hierarchy tools. What lives here: * A versioned hierarchy of every process the organization runs, with steps, policies, inputs, outputs, and dependencies * The full observation history of each process — deviations, exceptions, and the activity timelines behind them * The teams, systems, and controls referenced from each process ## Improve Use Within Advisor or this MCP in your AI tools to analyze thousands of processes at once — surface improvement opportunities, drive transformation, and build skills and agents grounded in how your business actually runs. ## What this means for your assistant Any question your assistant asks usually maps to one stage of the loop: | Question shape | Loop stage | Where to look | | ----------------------------- | ---------- | -------------------------------------------------- | | "What's our evidence for X?" | Discover | Observations, activity timelines, artifacts | | "How does X work today?" | Structure | Process Index — hierarchy, version, dependencies | | "Where should we focus next?" | Improve | Observations, process dependencies, recent changes | The [Tool reference](/tools/overview) is organized along the same axis. # Intelligence layers Source: https://developers.within.ai/concepts/intelligence-layers Within organizes operational intelligence into two layers. The MCP gives you query access to both. Within organizes operational intelligence into two layers — **Process Index (aka Process Context Graph)** and **Artifacts**. Each maps to a distinct set of MCP tools and is best for a different kind of question. | Layer | What it contains | Example questions | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | [Process Index](/concepts/process-index) (aka Process Context Graph) | Hierarchy, versions, steps, policies, dependencies, observations, activity timelines | "How does our vendor onboarding work?" "What changed in our close cycle last month?" | | [Artifacts](/concepts/artifacts) | Documents, videos, screenshots, session timelines | "Find the latest SOX compliance checklist." | ## How they fit together The Process Index is Within's context graph — the primary query surface for almost every question. It's where processes, their versions, their dependencies, and the observations captured against them live, all linked into one navigable structure. Artifacts are the underlying source documents and recordings the workspace has captured. The most useful answers chain across both layers in a single session: > "Give me the full picture on month-end close — process hierarchy, recent observations, and the most relevant docs." That single prompt fans out into a process search, hierarchy traversal, observation reads, activity timeline drills, and artifact lookups. Ten-plus tool calls, orchestrated automatically, answered with grounded evidence. ## When to start at each layer * **Start at the Process Index** when the user names a workflow, team, system, or business outcome — this is the default for almost every question. * **Start at Artifacts** when the user names a document, screenshot, or recording. The [Tool reference overview](/tools/overview) maps each entry path to the specific tools that begin the chain. # Process Index Source: https://developers.within.ai/concepts/process-index A living, hierarchical map of every process your organization runs. The **Process Index is Within's context graph of how work happens** — a versioned, hierarchical map of every process the organization runs, with the dependencies, teams, systems, and observations that connect them. It spans value streams at the top (P2P, O2C, close cycle) down to individual leaf processes that a person or system performs. Each process carries: * **Current version**: steps, policies, inputs, outputs, owner, team * **Version history**: how the process has evolved over time * **Dependencies**: which processes feed into this one, which depend on it * **Hierarchy node**: where it sits in the value stream * **[Observations](#observations)**: real-world deviations and exceptions captured against it * **[Linked artifacts](/concepts/artifacts)**: BRDs, SOPs, recordings, screenshots backing the process ## What you ask of it | User question | Tool to start with | | -------------------------------------- | ---------------------------------------------------------------- | | "Tell me about process X" | [`search`](/tools/entry-points) → [`fetch`](/tools/entry-points) | | "Browse the whole index" | [`get_process_hierarchy`](/tools/process-index) | | "Look up by exact team or name" | [`search_processes`](/tools/process-index) | | "Pull the rich nested payload" | [`get_process_details`](/tools/process-index) | | "What does this hierarchy node cover?" | [`get_hierarchy_node_details`](/tools/process-index) | ## Search → fetch → drill → drill further The default loop for any process question: 1. **Search** with the user's words. Iterate two to four times if results feel sparse — processes use organization-specific names, and single queries rarely cover broad topics. 2. **Fetch** the matched process to read steps, policies, dependencies, and history. 3. **Drill** into specific dependencies, hierarchy siblings, or version history when the summary isn't enough. 4. **Drill further** into the process's [observations](#observations) to see what actually happened in practice versus what's documented — the deviation patterns, exceptions, and activity timelines from real sessions. See [Tools by purpose → Process Index](/tools/process-index) and [Process observations](/tools/observations-and-changes) for the full toolset, and [Find opportunities](/guides/find-opportunities) for an end-to-end walkthrough. ## Observations The Process Index tells you what a process *should* be. **Observations** tell you what actually happened. An observation is a deviation or exception captured by the Within Companion during a real session. Observations are the most "primary source" evidence Within has — they record where the documented process and the executed process diverged. Each observation has: * A pointer to the process and version it was logged against * A short description of the deviation * A linked **activity timeline**: the exact sequence of user actions, with timestamps When a user asks "what changed?", "why does this run this way?", or "are there edge cases I should know about?", observations are the answer. | User question | Tool to start with | | ----------------------------------------------------------------------- | --------------------------------------------------------------- | | "What has been edited recently?" | [`get_recent_process_changes`](/tools/observations-and-changes) | | "What sessions have been recorded across the workspace?" | [`list_sessions`](/tools/observations-and-changes) | | "What exceptions has this process seen?" | [`get_process_observations`](/tools/observations-and-changes) | | "What did the user actually do in the session behind this observation?" | [`get_observation_citation`](/tools/observations-and-changes) | # FAQ Source: https://developers.within.ai/faq Common questions and gotchas from people setting up and using the Within MCP. If your question isn't here, reach out to [hello@within.ai](mailto:hello@within.ai). The most common cause is that the MCP hasn't been enabled in your Within workspace yet. Both OAuth and API-key auth require this one-time setup: 1. Log in to Within in a browser. 2. Go to **Settings → MCP**. 3. Pick the workspace you want to expose and complete the in-app setup. Then retry the sign-in or Bearer-token request from your AI client. See [Authentication → Enable the MCP in your workspace](/authentication#enable-the-mcp-in-your-workspace) for the canonical reference. Not directly. Within is a commercial service — you need an active workspace and a provisioned user account to use the MCP. Contact [hello@within.ai](mailto:hello@within.ai) to talk about access. Your organization's Within workspace admin needs to approve the Within connector (Claude) or app (ChatGPT) before users can sign in. Ask your admin, or have them reach out to [hello@within.ai](mailto:hello@within.ai). A connection is scoped to one workspace, so you switch at the auth level rather than from inside the assistant. How you do it depends on your authentication method: * **OAuth:** disconnect the Within connection in your client and reconnect. The reconnect flow shows a workspace picker. * **API key:** keys are bound to the workspace they were generated in. Generate a new key in the other workspace and swap the Bearer token in your client. See [Authentication → Switching workspaces](/authentication#switching-workspaces) for the full walkthrough. Go to **Settings → MCP** in your Within workspace. You can view, disable, or rotate existing keys from the same screen where you generated them. If you suspect a key has been exposed, revoke it immediately, generate a new one, and update your client configuration. See [Authentication → Keep keys safe](/authentication#keep-keys-safe). In your AI client, ask something like: ```text theme={null} Search Within for AI transformation opportunities across our processes — where could we build skills or deploy agents? ``` If the assistant calls the `search` tool and returns processes from your workspace, you're connected. If it falls back to generic answers or says it has no access to Within, the install hasn't completed — re-check the [install steps](/quickstart) for your client. No. Every tool in production is read-only. All process, artifact, and graph edits happen in the Within UI. See [Limitations](/limitations). Usually not. That response means the workspace doesn't yet have captured data covering the question — typically a capture gap, not an MCP bug. The gap itself is useful: it tells you what to capture next. If the question *should* have evidence and the assistant can't find it, try refining the query — single searches miss, and processes use organization-specific names. See [Operating principles](/tools/operating-principles). Any MCP-compatible client works. Use the install page that matches what you have today: * [Claude](/install/claude) * [Claude Code](/install/claude-code) * [ChatGPT](/install/chatgpt) * [Codex](/install/codex) * [Cursor](/install/cursor) * [Gemini CLI](/install/gemini-cli) * [GitHub Copilot](/install/github-copilot) # Build skills, agents, and automations Source: https://developers.within.ai/guides/agent-builder A guided way to turn how your organization works into skills, agents, and automations, grounded in your real processes. Agent Builder helps you turn the way your organization already works into something you can reuse: a skill, an agent, an automation, or a lighter change like a shared prompt or project. It analyzes your workspace, surfaces opportunities, and helps you decide what to build, grounded in your real processes rather than generic guesses. You can use it to start something new, pick up an existing project in a fresh chat, or get help deciding what to do next. ## Get started Just tell your assistant what you're trying to do. For example, "use Within to identify automation opportunities in our order-to-cash value stream" or "help me find something worth automating in procurement." It recognizes the intent, pulls in what it needs, and guides you through the rest. ## The tools behind it Under the hood, the assistant uses the [Agent Builder tools](/tools/agent-builder) to fetch what it needs and guide you. You don't call these yourself. The assistant reaches for them when you describe what you want to build. # Chain with other connectors Source: https://developers.within.ai/guides/chain-with-connectors Within for context, Gmail / Slack / Linear / Notion / Calendar / Drive for action. Claude and ChatGPT both support multiple MCP connectors in the same session. Use Within for organizational context, then chain into another connector to act on what you found — without breaking out of the conversation. The pattern: **Within provides the knowledge. Other connectors provide the action surface.** ## Example prompts | Prompt | Connectors chained | | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | "Look at our customer onboarding process and draft an email to the implementation team summarizing the current state and open issues." | Within → Gmail | | "Find all processes that changed this week and post a summary to `#ops-updates` in Slack." | Within → Slack | | "Check our QBR preparation process and create Linear tickets for each step that's currently manual." | Within → Linear | | "Look at our SOX-controlled processes and create a Notion page documenting the current control matrix." | Within → Notion | | "Find the process owner for invoice reconciliation and schedule a 30-minute review with them." | Within → Google Calendar | | "Pull our vendor management process docs and save a summary to Google Drive." | Within → Google Drive | ## Why this works A single MCP call answers a narrow question. A chain across connectors produces a deliverable. The MCP layer is stateless per call, so the assistant can fan out and combine results freely in one turn. For each example above, the assistant typically: 1. Searches and fetches the relevant process from Within. 2. Pulls observations and recent changes for current-state grounding. 3. Hands the synthesized context to the second connector to take action. ## Practical tips * **Name the deliverable**, not the tool. "Draft an email" is better than "use Gmail" — let the assistant pick. * **Constrain by scope**. "In our P2P value stream" or "owned by the finance team" gives the assistant a tractable subtree to walk. * **Ask for citations**. Within tools return process IDs, observation timestamps, and artifact IDs. A good deliverable threads those back in so the recipient can verify. # Combine with deep research Source: https://developers.within.ai/guides/deep-research Internal reality vs. external benchmarks — gap analysis the assistant writes itself. Claude and ChatGPT both have web search built in. Combine that with the Within MCP and you get gap analysis that would take a human days to assemble. The pattern: **Within tells the assistant what you actually do. Web research tells it what you should be doing. The gap writes itself.** ## Example prompts | Prompt | What you get | | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | "Look at our accounts payable process and research industry best practices — where are we behind?" | Your actual process graph measured against published frameworks | | "Compare our vendor onboarding to what Gartner recommends for companies our size." | Analyst-grade benchmarking grounded in your specific process definitions | | "Research how leading companies automate the manual steps in our order-to-cash flow." | Targeted research pinpointed to your specific bottlenecks and manual handoffs | | "What compliance frameworks apply to our data handling processes, and are we meeting them?" | Cross-reference your documented controls with current regulatory guidance | | "What are the emerging risks in our industry for processes that involve PII handling?" | Threat landscape analysis mapped to your actual process surface area | ## Recipe Call [`search`](/tools/entry-points) → [`fetch`](/tools/entry-points) → [`get_process_details`](/tools/process-index) to read the current state of the target process. Call [`get_process_observations`](/tools/observations-and-changes) and [`get_observation_citation`](/tools/observations-and-changes) — your real deviations, not assumed ones. Use the client's web search — and any other tools available in your environment (browser, file search, internal knowledge bases) — to gather published frameworks, vendor positioning, or regulatory guidance. "Your process does X today, with these deviations. The framework recommends Y. The gap is Z — here's the evidence for both sides." ## Watch for * **Don't anchor on web findings alone.** The workspace is the ground truth. If a benchmark contradicts what observations show, the benchmark is the hypothesis. * **Cite both sources.** Process IDs, observation timestamps, and source URLs side by side. That's what makes the gap analysis defensible. # Find transformation opportunities Source: https://developers.within.ai/guides/find-opportunities Rank the highest-leverage automation and transformation candidates across the index. A platform lead, AI architect, or transformation owner asks where to focus next. This is the "spin up multiple agents to scan the entire process tree" use case — agents should fan out in parallel across the hierarchy. ## Example prompts * "Find the highest-leverage automation opportunities in our P2P value stream." * "Where in our close cycle should we focus next?" * "Scan our org for duplicate invoice processing across geographies." ## End-to-end recipe Call [`list_accessible_workspaces`](/tools/workspace) and switch if needed. Call [`get_process_hierarchy`](/tools/process-index) — the whole tree, or filtered to the value stream of interest. The leaves become your work queue. For each leaf: * [`get_process_details`](/tools/process-index) — current version, steps, dependencies. Note step count, manual vs system steps, exception count. * [`get_process_observations`](/tools/observations-and-changes) — exception volume per process (default summary verbosity). The MCP is stateless per call. There's no penalty for parallel reads — fan out aggressively. Call [`search`](/tools/entry-points) directly on the index with pattern queries: "manual approval", "duplicate entry", "data re-keying", "exception handling", "swivel-chair workflow". For each hit, [`fetch`](/tools/entry-points) the process to confirm the pattern is real, not just a name match. Inspect the `attributes` field already returned by [`get_process_details`](/tools/process-index) — "automation status", "system of record", "control level", or similar attributes that help rank candidates. For each top candidate: * [`get_process_observations`](/tools/observations-and-changes) with `verbosity="full"` — confirm the deviation or manual pattern with concrete evidence. * Read the `dependencies` field already returned by [`get_process_details`](/tools/process-index) for a first cut at blast radius. Process IDs, observation counts, dependency depth, similarity to known patterns, evidence trail. ## What to surface in the brief * A ranked list of candidate processes * For each: observation count, dependency depth, pattern signal * Citable process IDs and observation timestamps * Gaps where the workspace doesn't have enough evidence yet # Help a process performer Source: https://developers.within.ai/guides/process-performer Do the task the way your team actually does it, not the way ChatGPT thinks it's done. A process performer — an AP lead, ops manager, recruiter, analyst — asks their assistant to do real work: vendor reconciliation, invoice approval, candidate screening, ERP migration prep, audit walkthrough. The assistant should pull the customer's existing process before improvising. ## Example prompts * "Walk me through how to reconcile this batch of vendor invoices." * "Help me prep for tomorrow's SOX walkthrough." * "I'm onboarding a new vendor — what's our checklist?" ## End-to-end recipe Call [`list_accessible_workspaces`](/tools/workspace) to confirm the active workspace. If the user names a different one, they'll need to [switch workspaces](/authentication#switching-workspaces) — the assistant can't change it mid-session. Call [`search`](/tools/entry-points) with the task in the user's words ("vendor invoice reconciliation"). Iterate two to four times with refined queries — single queries rarely cover broad topics. If results are still sparse, call [`get_process_hierarchy`](/tools/process-index) to orient on the right value stream, then drill in. Use [`fetch`](/tools/entry-points) to read steps, policies, inputs, outputs, and dependencies. If you need the richer nested payload (full version metadata or every dependency ID), call [`get_process_details`](/tools/process-index) directly. Call [`get_process_observations`](/tools/observations-and-changes) to find emerging edge cases and exception patterns. Default `verbosity="summary"` is the scan; bump to `"full"` when you want the rich payload inline. Call [`get_observation_citation`](/tools/observations-and-changes) to read the exact user actions behind a deviation. This is the most "primary source" evidence the workspace has. If the task touches another team or system, read the `dependencies` field already returned by [`get_process_details`](/tools/process-index). To go deeper on a handoff, [`fetch`](/tools/entry-points) the referenced upstream or downstream process and read its steps and observations the same way. "Here's how your team does this. Here's the deviation pattern from last quarter. Here's what to watch for." ## Catch duplication If the user suspects a different team already does this work, run [`search`](/tools/entry-points) again with broader queries — task name, system, business outcome — across the whole workspace. If results look similar to the current process, `fetch` each candidate and compare steps and observations side by side. Surface the duplicate set with process IDs. # State-of-the-team report Source: https://developers.within.ai/guides/state-of-team What's running, what's changing, what's deviating, what needs the manager's attention. A team manager is checking in on the processes they own. The assistant should produce a concise, evidence-backed brief — not a feature dump. ## Example prompts * "Give me a state-of-the-team report on the processes we own." * "What's changed in our P2P team's processes this quarter?" * "Onboard a new joiner to how this team runs." ## End-to-end recipe Call [`list_accessible_workspaces`](/tools/workspace) and switch if needed. Call [`get_process_hierarchy`](/tools/process-index) rooted at the team's value-stream node. Call [`get_recent_process_changes`](/tools/observations-and-changes) — the workspace-wide feed of recently-edited process versions, filtered to this team's tree. Use this as your shortlist. For each process from the previous step: * [`get_process_details`](/tools/process-index) for current state, dependencies, and version label * [`get_process_observations`](/tools/observations-and-changes) for a recent observation summary (default `verbosity="summary"`) Call [`get_observation_citation`](/tools/observations-and-changes) on the top two or three observations for primary-source detail. "Your team owns N processes. M changed in the last 30 days. K are showing deviation patterns worth your attention. Here are the top 3 with evidence." ## Ramp a new joiner The same chain works for onboarding a new person (or a fresh agent): walk the team's part of the hierarchy, fetch the top processes, surface dependencies and recent changes. Ground the joiner in the team's actual operational reality, not in generic role-based assumptions. ## Prove control coverage For audit-readiness questions ("where is control X supported?", "what's our evidence for policy Y?"), pull the relevant processes, surface the policies attached to the current version, and cite the supporting observations and activity timelines. The `attributes` field on [`get_process_details`](/tools/process-index) surfaces the workspace's custom compliance attributes if the user asks about a specific control type. # Form a transformation thesis Source: https://developers.within.ai/guides/transformation-thesis Current state, blast radius, and intervention points — with evidence, on a specific process or value stream. The user has zeroed in on a target process or value stream and wants the assistant to build a deep, evidence-grounded transformation thesis before recommending changes. ## Example prompts * "Build a transformation thesis for our order-to-cash process." * "We want to redesign vendor onboarding — give me current state, blast radius, and intervention points." * "If we deprecate System X, what breaks?" ## End-to-end recipe Call [`list_accessible_workspaces`](/tools/workspace) and switch if needed. Call [`search`](/tools/entry-points) → [`fetch`](/tools/entry-points), or [`fetch`](/tools/entry-points) directly if the ID is known. Then [`get_process_details`](/tools/process-index) for the full nested payload: current version, dependencies, hierarchy node, version history. Call [`get_hierarchy_node_details`](/tools/process-index) — parent value stream, sibling processes that may share patterns. Call [`get_recent_process_changes`](/tools/observations-and-changes) — version evolution. What has the team been changing? In which direction? Call [`get_process_observations`](/tools/observations-and-changes) across versions. Look for repeated deviation patterns, exception types, manual workarounds. For three to five representative observations, call [`get_observation_citation`](/tools/observations-and-changes) — primary-source detail of how the process runs in practice (not how it's documented). The `dependencies` field on `get_process_details` lists the upstream and downstream processes by ID. For each one, [`fetch`](/tools/entry-points) the process, then call [`get_process_details`](/tools/process-index) for the full payload. Read its steps, its own dependencies, and its recent observations. Repeat for as many hops as the thesis needs: * **Upstream**: what feeds this. Root cause / input quality matters for transformation viability. * **Downstream**: blast radius if we change it. Surfacing this early prevents under-scoped proposals. For high-impact transformation theses, drill the most-affected dependencies one more level — call [`get_process_observations`](/tools/observations-and-changes) and [`get_observation_citation`](/tools/observations-and-changes) on the dependencies whose behavior shapes your conclusions. From the [`get_hierarchy_node_details`](/tools/process-index) payload returned earlier, [`fetch`](/tools/entry-points) two or three sibling processes under the same value stream. If they share patterns, controls, or systems with the target, the transformation thesis may need to address them too. Structure the answer as: * **Current state**: how the process actually runs (cite observations). * **Blast radius**: upstream feeders and downstream dependents. * **Pain pattern**: the deviation, manual, or duplication signal — with evidence. * **Intervention points**: where to change, ranked by leverage and risk. * **Open questions**: what evidence is missing that would strengthen or invalidate the thesis. # Within MCP Source: https://developers.within.ai/index Bring your organization's process intelligence into your AI tools. Understand how work happens, identify opportunities, and agentify your business. Within MCP is available for all enterprise customers. Click [Quickstart](/quickstart) below to get started agentifying your business. ## Why connect it The MCP does everything Within Advisor does today — and more. The unlock is surface area: the MCP embeds your organization's process intelligence inside an environment that can act on it — writing code, chaining with other connectors, building agents, and producing deliverables grounded in how your business actually runs. Pick a client, authenticate, and ask your first question in under five minutes. OAuth for supported clients, API key for everything else. How Within captures, structures, and improves how work happens. End-to-end recipes for the most common things assistants do with the MCP. Every tool the MCP exposes, grouped by what you're trying to do. Answers to the most common install, auth, and behavior questions. ## What you get access to Within organizes operational intelligence into two layers — **Process Index (aka Process Context Graph)** and **Artifacts** — and the MCP gives your assistant query access to both. | Layer | What's in it | Example questions | | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | [**Process Index**](/concepts/process-index) (aka Process Context Graph) | Process hierarchy, versions, steps, dependencies, observations, activity timelines | "How does our vendor onboarding work?" "What changed in our close cycle last month?" | | [**Artifacts**](/concepts/artifacts) | Documents, videos, audio, diagrams, screenshots, logs — all searchable | "Find the latest SOX compliance checklist." | See [Intelligence layers](/concepts/intelligence-layers) for the full mental model. ## What you can do A human using the Advisor might run two or three tools per question. An LLM in an agentic loop can chain ten or more — searching, drilling in, cross-referencing, synthesizing. That's the unlock. Do the task the way your team actually does it. What's changing, what's deviating, what needs attention. Rank automation and transformation candidates by leverage. Current state, blast radius, and intervention points — with evidence. Within for context, Gmail/Slack/Linear/Notion for action. Turn how your organization works into skills, agents, and automations. ## Get a workspace Within is a commercial service. You need an active workspace and user account to use the MCP. Contact [hello@within.ai](mailto:hello@within.ai) if your organization is not yet a customer. # ChatGPT Source: https://developers.within.ai/install/chatgpt Install the Within app in ChatGPT. In ChatGPT, click **Apps**. Search for **Within** and click **Connect**. You'll be redirected to Within to authenticate. The assistant can then query your active workspace. Your organization may need to approve the app first, and you must be provisioned as a user in Within for the connection to succeed. ## Verify In ChatGPT, ask: ```text theme={null} Search Within for AI transformation opportunities across our processes — where could we build skills or deploy agents? ``` The assistant should call `search` and return process results from your workspace. ## If you don't have access If your organization hasn't approved the Within app yet, or you can't see it in ChatGPT's app picker, install from one of the [other clients](/quickstart) instead. # Claude Source: https://developers.within.ai/install/claude Install the Within connector in Claude. Once enabled, connector works across **Claude**, **Claude Cowork**, and **Claude Code**. In Claude, go to **Customize → Connectors**. Search for **Within** and click **Connect**. You will be redirected to Within to authenticate. Your assistant will then have access to your active workspace. Your organization may need to approve the connector first, and you must be provisioned as a user in Within for the connection to succeed. ## Verify In Claude, ask: ```text theme={null} Search Within for AI transformation opportunities across our processes — where could we build skills or deploy agents? ``` The assistant should call `search` and return process results from your workspace. ## If you don't have access If your organization hasn't approved the Within connector yet, or you can't see it in Claude's connector directory, install from one of the [other clients](/quickstart) instead. # Claude Code Source: https://developers.within.ai/install/claude-code Install the Within plugin or register the MCP server in Claude Code. Two install paths are supported. The plugin path is preferred — it ships the bundled skill prompt and uses OAuth. ## Plugin install (preferred, OAuth) From a Claude Code session, run these two commands one after the other. ```text theme={null} /plugin marketplace add Within-AI/within-mcp ``` ```text theme={null} /plugin install within@within ``` The first request that hits a Within tool will prompt you to authenticate. ## Manual MCP add (API key) Use this for long-running background agents. Generate an API key from `Settings → MCP` in your Within workspace (see [Authentication](/authentication#api-key)), then run: ```bash theme={null} claude mcp add --transport http within \ https://api.within.ai/mcp \ --header "Authorization: Bearer " ``` Treat the API key like a password. Anyone with the key can query your Within workspace. Rotate it from `Settings → MCP` if it's exposed. ## Verify In a Claude Code session, ask: ```text theme={null} Search Within for AI transformation opportunities across our processes — where could we build skills or deploy agents? ``` The assistant should call `search` and return process results from your workspace. # Codex Source: https://developers.within.ai/install/codex Register the Within MCP server with the OpenAI Codex CLI. Two install paths are supported. The plugin path is preferred — it ships the bundled skill prompt and uses OAuth. ## Plugin install (preferred, OAuth) Codex splits this into a shell command to register the marketplace, then a slash command inside Codex to install the plugin. ```bash theme={null} codex plugin marketplace add Within-AI/within-mcp ``` Open the plugins picker: ```text theme={null} /plugins ``` Search for **Within** and install the plugin. The first request that hits a Within tool will prompt you to authenticate. ## Config file install (API key) Use this for long-running background agents. Generate an API key from `Settings → MCP` in your Within workspace (see [Authentication](/authentication#api-key)) and add the server to `~/.codex/config.toml`: ```toml theme={null} [mcp_servers.within] url = "https://api.within.ai/mcp" bearer_token_env_var = "WITHIN_MCP_TOKEN" ``` Set the environment variable in your shell profile (`~/.zshrc`, `~/.bashrc`): ```bash theme={null} export WITHIN_MCP_TOKEN= ``` Restart your terminal (or source the profile) so Codex picks up the new variable. Treat the API key like a password. Rotate it from `Settings → MCP` in Within if it's exposed. ## Verify In a Codex session, ask: ```text theme={null} Search Within for AI transformation opportunities across our processes — where could we build skills or deploy agents? ``` The assistant should call `search` and return process results from your workspace. # Cursor Source: https://developers.within.ai/install/cursor Register the Within MCP server in Cursor. Cursor supports both install paths. The OAuth path is preferred — Cursor manages the token for you and there's no key handling. ## OAuth install (preferred) In Cursor, open **Settings → Tools & MCP → New MCP Server** (or edit `.cursor/mcp.json` directly) and add the Within server: ```json theme={null} { "mcpServers": { "within": { "type": "http", "url": "https://api.within.ai/mcp" } } } ``` Save and reload MCP servers. Cursor detects that the server requires OAuth and shows a **Connect** button in the MCP panel. Click it — you'll be redirected to Within to sign in, and Cursor stores the resulting credentials for you. ## API key install Use this for long-running background agents. Generate an API key from `Settings → MCP` in your Within workspace (see [Authentication](/authentication#api-key)) and add it as a Bearer header: ```json theme={null} { "mcpServers": { "within": { "type": "http", "url": "https://api.within.ai/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Reload MCP servers from the settings panel. The Within tools should appear in the MCP tool list. Treat the API key like a password. Don't commit `.cursor/mcp.json` with a live key — use a global config (`~/.cursor/mcp.json`) or env-var reference instead. Rotate keys from `Settings → MCP` in Within if exposed. ## Verify In a Cursor chat, ask: ```text theme={null} Search Within for AI transformation opportunities across our processes — where could we build skills or deploy agents? ``` The assistant should call `search` and return process results from your workspace. # Gemini CLI Source: https://developers.within.ai/install/gemini-cli Install the Within extension in the Gemini CLI. ## Extension install (OAuth) ```bash theme={null} gemini extensions install https://github.com/Within-AI/within-mcp ``` ```text theme={null} /mcp auth within ``` You'll be redirected to Within in your browser to authenticate. ## API key install Use this for long-running background agents. Generate an API key from `Settings → MCP` in your Within workspace (see [Authentication](/authentication#api-key)) and configure your Gemini CLI's MCP block to send the `Authorization: Bearer ` header for `within`. Treat the API key like a password. Rotate it from `Settings → MCP` in Within if it's exposed. ## Verify In a Gemini CLI session, ask: ```text theme={null} Search Within for AI transformation opportunities across our processes — where could we build skills or deploy agents? ``` The assistant should call `search` and return process results from your workspace. # GitHub Copilot Source: https://developers.within.ai/install/github-copilot Register the Within MCP server in the GitHub Copilot CLI and desktop app. Copilot has no plugin marketplace, so register the MCP server directly. The CLI and the desktop app read the same MCP configuration (`~/.copilot/mcp-config.json`), so registering the server once makes it available in both. OAuth is the preferred auth path. Use an API key for long-running background agents. Because there's no plugin, the bundled skill prompt that ships with the Claude Code and Codex installs isn't included. The MCP tools work the same, the assistant just starts without the extra prompt guidance. ## OAuth install (preferred) From your shell: ```bash theme={null} copilot mcp add --transport http within https://api.within.ai/mcp ``` Or in the desktop app: open settings, go to **MCP servers**, click **Add server**, then **Add custom server**. Name the server `within`, switch the type from **Local** to **HTTP**, and enter `https://api.within.ai/mcp` as the URL. Leave **Headers** and **OAuth Client ID** empty. Copilot prompts you to authenticate the first time it uses the server. The CLI shows the prompt when you open a session, and the desktop app shows a **Sign in** button on the `within` row under **MCP servers** in settings. Complete the sign-in in your browser once; the credential is shared between the CLI and the app. ## API key install Use this for long-running background agents. Generate an API key from `Settings → MCP` in your Within workspace (see [Authentication](/authentication#api-key)), then register the server with an Authorization header: ```bash theme={null} copilot mcp add --transport http \ --header "Authorization: Bearer " \ within https://api.within.ai/mcp ``` Or add it to `~/.copilot/mcp-config.json` directly: ```json theme={null} { "mcpServers": { "within": { "type": "http", "url": "https://api.within.ai/mcp", "headers": { "Authorization": "Bearer " }, "tools": ["*"] } } } ``` In the desktop app, the same header goes in the **Headers** fields of the add-server form: `Authorization` as the name, `Bearer ` as the value. Treat the API key like a password. Anyone with the key can query your Within workspace. Rotate it from `Settings → MCP` in Within if it's exposed. ## Verify Run `/mcp show` in a CLI session (or check **MCP servers** in the desktop app's settings) to confirm `within` is listed. If it isn't, quit and reopen Copilot. The configuration is read at startup, so a server added while a session was open, or added from the other surface, won't appear until a restart. Then ask: ```text theme={null} Search Within for AI transformation opportunities across our processes — where could we build skills or deploy agents? ``` The assistant should call `get_agent_builder_instructions` and start working from your workspace's processes. # Limitations Source: https://developers.within.ai/limitations What the MCP does not do today — and what's coming. The Within MCP is read-mostly and scoped intentionally. Knowing where it stops keeps assistant behavior honest. ## Read-only access Tools available through the MCP are query-only. You can search, read, explore, and analyze. You cannot create or modify processes, artifacts, or graph entities through the MCP — those writes happen in the Within UI. ## Authentication coverage OAuth is supported in Claude, ChatGPT, Claude Code (via the plugin), Codex (via `codex mcp login`), Cursor (via the **Connect** button on remote MCP servers), and Gemini CLI (via `/mcp auth`). For any client that doesn't yet support MCP OAuth, use the API key fallback. See [Authentication](/authentication) for the full breakdown. ## Workspace scope Each connection is scoped to one Within workspace. If the user belongs to multiple workspaces, they switch by reconnecting (OAuth) or by using a key generated in the other workspace (API key) — see [Authentication → Switching workspaces](/authentication#switching-workspaces). ## Tool surface evolves The production tool catalog grows over time as new Within capabilities ship (additional graph traversals, write tools for specific safe operations). The [Tool reference](/tools/overview) is the live source of truth — check there before assuming a tool exists. ## When to fall back to the UI * Bulk edits to processes or artifacts. * Configuring workspace-level attributes or policies. * Inviting users or managing roles. For everything else, the MCP should be enough — and if it isn't, [reach out](mailto:hello@within.ai). # Quickstart Source: https://developers.within.ai/quickstart Pick a client, authenticate, and ask your first question. You need an active Within workspace and a user account. If you're not sure whether your organization has one, contact [hello@within.ai](mailto:hello@within.ai). Within MCP works with any MCP-compatible client. Use the install page that matches yours. Anthropic assistant Anthropic CLI OpenAI assistant OpenAI CLI IDE Google CLI GitHub CLI and app Two methods are supported: * **OAuth** — preferred where the client supports it. Sign in to Within from the client; no key handling. * **API key** — used in alpha clients and as a fallback. Generate a key from `Settings → MCP` in your Within workspace and pass it as a `Bearer` token. See [Authentication](/authentication) for the full setup. Start with something concrete from your workspace. The MCP is most useful when the question references *your* processes, systems, or teams. Examples: * "How does our vendor onboarding process work today?" * "What changed in our month-end close in the last 30 days?" * "Which processes depend on System X?" * "Find the highest-leverage automation opportunities in our P2P value stream." See [How-to guides](/guides/process-performer) for end-to-end recipes. ## What to expect The first time the assistant calls a Within tool, it will prompt you to authenticate (OAuth) or read your configured API key. After that, the assistant chains MCP tools in the background — searching the Process Index, fetching specific processes, pulling observations, and drilling into the activity timelines behind those observations — and answers in business language, citing the workspace evidence behind each claim. If the assistant cannot find evidence for a claim in your workspace, it should say so plainly. That gap is itself useful information. ## Next steps The Discover → Structure → Improve loop, and the three intelligence layers. Every tool the MCP exposes, with selection guidance. # Security & architecture Source: https://developers.within.ai/security How Within MCP connects to your AI tools, how it authenticates, and how authorization mirrors the Within web application. The Within MCP is a read-only view into your organization's process intelligence. This page is the canonical reference for security, architecture, and access-control questions — written so InfoSec, IT, and platform reviewers can use it directly. ## Integration scope The MCP does not integrate with external LLMs directly. Your AI client (Claude, ChatGPT, Cursor, and so on) connects to the MCP and uses whatever LLM that client runs. The MCP supplies process intelligence; the client supplies the model. Supported clients today: | Surface | Clients | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | IDEs / CLIs | [Claude Code](/install/claude-code), [Codex](/install/codex), [Cursor](/install/cursor), [Gemini CLI](/install/gemini-cli), [GitHub Copilot](/install/github-copilot) | | Conversational assistants | [ChatGPT](/install/chatgpt) (via the OpenAI app store); [Claude](/install/claude) (via the Anthropic connector directory) | If the AI client doesn't run inside an IDE, the MCP plugs into the assistant's app/connector layer instead. The connection model is the same in either case: the client talks to a single MCP endpoint over HTTPS using the [Model Context Protocol](https://modelcontextprotocol.io/). ## Architecture The MCP runs on the same infrastructure that powers the Within web application you already use. There is no separate data plane. | Property | Value | | ------------- | -------------------------------------------------------------- | | **Transport** | HTTPS-based Model Context Protocol over TLS | | **Endpoint** | `https://api.within.ai/mcp` | | **Backend** | Same API and data store that serves the Within web application | Every MCP request flows into the same backend as a request from the web app. There is no shortcut path that bypasses normal validation or access control. ## Authentication Two methods are supported. Pick based on whether the session is interactive or automated. | Method | When to use | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **OAuth** | Recommended for human, interactive sessions. Same sign-in flow as the Within web app — the AI client manages the token after sign-in. | | **Long-lived API key** | Recommended for background or automated agents. Generated from `Settings → MCP` in Within. Sent as a `Bearer` token on every request. | API keys are revocable at any time from the same `Settings → MCP` screen. See [Authentication](/authentication) for per-client setup details. ## Authorization Authorization is enforced by the same layer as the Within Advisor web application. The MCP can only access what the authenticated user — or, for API keys, the user the key was issued for — can access in the web app: * **Workspace boundaries** are enforced identically. MCP requests cannot read across workspaces the user is not a member of. * **Per-resource permissions** are enforced identically. If a user cannot see a process, observation, artifact, or graph entity in the web app, the MCP returns the same answer. * There is **no MCP-only access path** that bypasses the normal authorization layer. In short, the MCP inherits the user's existing posture. Granting MCP access does not broaden what a user can already see. ## Read-only data scope All tools exposed by the MCP in production are **read-only**. The MCP does not modify user-facing data and cannot read across workspaces — each connection is scoped to a single workspace, set by the authenticated user's session or the workspace the API key was issued for. The MCP cannot: * Create or modify processes, artifacts, observations, or graph entities * Edit policies, attributes, or workspace configuration * Invite users, manage roles, or change permissions All write operations happen in the Within UI. See [Limitations](/limitations) for the full out-of-scope list. ## Summary for reviewers * **Connection**: AI client ↔ Within MCP over HTTPS + TLS. No direct external LLM integration; LLMs live inside the AI client. * **Hosting**: Same infrastructure as the Within web application. * **AuthN**: OAuth (interactive) or long-lived API key (automated). Both revocable from `Settings → MCP`. * **AuthZ**: Identical to the Within web app — same workspace and per-resource permissions. * **Data scope**: Read-only. Cannot bypass user permissions. If your review needs detail not covered here, reach out at [hello@within.ai](mailto:hello@within.ai). # Agent Builder Source: https://developers.within.ai/tools/agent-builder Fetch the Agent Builder instructions and the resources used to build with them. Agent Builder is a guided way to turn how your organization works into skills, agents, and automations. Two tools drive it. | Tool | What it does | | -------------------------------- | --------------------------------------------------------------- | | `get_agent_builder_instructions` | Fetches the instructions relevant to the Agent Builder process. | | `get_agent_builder_resource` | Fetches a resource used while building. | See the [Build skills, agents, and automations](/guides/agent-builder) guide for how to get started. # Artifacts Source: https://developers.within.ai/tools/artifacts Find and read the documents, recordings, and source files behind processes. Artifacts are the underlying documents, recordings, and source files behind processes — BRDs, SOPs, video recordings, screenshots, audio, diagrams, logs. | Tool | When to use | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search_artifacts` | Hybrid semantic + lexical search across artifact text. Returns ranked results with short context snippets. **Start here** for artifact discovery. | | `get_artifact_details` | Full metadata for a single artifact by `resource_key` — type, status, file info, and linked artifacts (`input_artifacts`, `output_artifacts`, `children`). | | `get_artifact_content` | Full or range-mode text extraction for a single artifact. Use range mode (`start_line` / `end_line`) when you need to cite specific lines. | | `search_artifact_text` | Within one artifact (by `resource_key`), find line-numbered matches with surrounding context. Regex or literal. There is no cross-document text search on the external surface — for multi-document retrieval, use `search_artifacts`. | ## Common chains * **Cite a passage**: `search_artifacts` → `get_artifact_content` with a line range → quote the lines back to the user * **Read a full SOP**: `search_artifacts` (find by query) → `get_artifact_content` (full text) * **Search inside one artifact**: `search_artifacts` (find the artifact) → `search_artifact_text` (locate specific mentions by regex or literal) * **Trace lineage**: `get_artifact_details` → walk `input_artifacts` / `output_artifacts` / `children` to find related sources # Standard entry points Source: https://developers.within.ai/tools/entry-points The default starting path for any process question. Most ChatGPT, Claude, and standard MCP clients will begin every Within interaction with one of these two tools. | Tool | When to use | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search` | First call for almost any process question. Semantic search over the customer's process index. **Iterate** — single queries rarely cover broad topics, and processes use organization-specific names. | | `fetch` | Pull full details for one process by ID returned from `search` or hierarchy navigation: placement in the index, current version (steps, policies, linked artifacts), dependencies, history. Fetch dependency IDs to walk relationships. | ## The default loop Query in the user's words. Refine two to four times if results feel sparse. Pull the matched process. Read steps, policies, linked artifacts, and dependencies. If `fetch`'s summary isn't enough, drop into [Process Index tools](/tools/process-index) for the richer payload, then chain into [observations and activity timelines](/tools/observations-and-changes) for primary-source evidence. ## When to skip `search` If the user has already named a specific process or you have the ID from a prior call, go straight to `fetch`. If the user wants to *browse* rather than search, start with [`get_process_hierarchy`](/tools/process-index) instead. # Process observations Source: https://developers.within.ai/tools/observations-and-changes Pull the evidence trail behind a process — what changed, what happened, why it ran this way. Use these tools when the user asks "what changed?", "what happened?", or "why does this run this way?" | Tool | When to use | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_recent_process_changes` | Workspace-wide version-change feed. "What has been edited recently?" | | `get_process_observations` | Observations on a specific process. Each surfaces the friction signals — `rationale`, `windows_time_frame`, `negative_deviations`, `positive_deviations` — and a session reference. Default response is the summary shape; pass `verbosity="full"` to also include the runtime inputs, outputs, and the step-by-step narrative (heavy — use a small `limit`). Optional version filter. | | `get_observation_citation` | The activity timeline behind an observation: what the user did, when, on which systems. The most "primary source" evidence Within has. Pass the `observation_resource_key`; use `verbosity` (`low`/`medium`/`high`) for detail, and `activity_block_index` to page through the timeline one block at a time. Only works for your own sessions. | | `list_sessions` | Recent workspace sessions, paginated. Each entry returns the processes the session updated, its duration, and who created it — a quick way to see recent activity and who's driving it. | ## What an observation is An observation is a captured execution of a process — a real session, attached to a specific process and version. The **activity timeline** is the underlying sequence of user actions that produced the observation — the systems they used, what they did, when. If you only call one tool from this group, call `get_observation_citation` on a top observation. It is the closest thing the workspace has to a video replay. It only works for your own sessions. ## Common chains * **State-of-team brief**: `get_recent_process_changes` → drill into specific processes via [`fetch`](/tools/entry-points) or `get_process_details` * **Deep-dive on a process**: `get_process_observations` (summary mode, scan the friction signals) → pick the most relevant → re-call with `verbosity="full"` for the narrative, or jump straight to `get_observation_citation` for the activity timeline * **Confirm a transformation candidate**: `get_process_observations` for exception patterns → `get_observation_citation` to confirm the manual pattern with concrete evidence ## Cite what you find Observations have timestamps and version pointers. When the user asks "what's the evidence?", surface the observation timestamp and the version it was logged against — that's a citation the user can audit in Within. ## Deviations Each observation carries the agent's per-session understanding of how that run compared to the documented process: * **Positive deviations** — places where the user went *beyond* the documented path in a useful way: a shortcut, a better validation step, a quality-improving move worth promoting. * **Negative deviations** — friction or workarounds: an extra manual step, a retry, a small fix to keep moving. Both are judgments made in isolation against one session's activity timeline. Per-session friction often looks routine on its own, so `negative_deviations` is frequently empty on individual observations even when a pattern is present across many sessions. ### How to use deviations A single observation gives you the single-session view. The signal most teams want — "the same workaround appears on 4 of 5 captures," "this retry is systemic" — is **cross-observation deviation analysis**: the surface-level patterns that only emerge when you aggregate across the observation set for a process. Two paths: 1. **Within Advisor** does this aggregation natively across the workspace. 2. **MCP-stitched**: pull `get_observation_citation` across the observation set for the process, then diff against the pinned process version yourself. The MCP exposes everything Advisor reads — the cross-observation pass is what you stitch. # Operating principles Source: https://developers.within.ai/tools/operating-principles How an assistant should think while calling Within MCP tools. These principles apply to every tool in the catalog. They keep answers grounded, citable, and useful. ## 1. Iterate on search Single queries miss. Processes use organization-specific names, and a broad topic rarely surfaces in one call. Be willing to refine two to four times before falling back to hierarchy browsing. ## 2. Stay grounded Cite Within evidence when available — process IDs, artifact IDs, observation timestamps. Do not invent facts the workspace does not support. ## 3. Separate observed from inferred > "Observed: X happens at step 3." > "Inferred: this is likely a duplication of Y based on similar steps in Z." This distinction matters more than any single tool call. ## 4. Call out gaps If the workspace does not have evidence, say so plainly. That gap is itself useful information for the customer — it's how they learn what to capture next. ## 5. Read-only Every tool in production is read-only. The MCP never mutates workspace state — all edits happen in the Within UI. ## 6. `search_*` returns starting points, not answers `search`, `search_processes`, and `search_artifacts` all return short snippets meant to help you locate the right object. Always chain into a `get_*` or `fetch` call to read the full content before answering. Snippets are the lookup, not the citation. ## 7. Let the assistant chain tools The best results come from open-ended prompts that let the model decide which tools to call and in what order. Describe what you want to know, not how to get it. The MCP is stateless per call — there's no penalty for parallel reads. # Tool reference Source: https://developers.within.ai/tools/overview Every tool the Within MCP exposes in production, organized by what you're trying to do. The Within MCP exposes a read-only set of tools that an AI assistant can chain to answer real questions grounded in a customer's workspace. The point of this reference is not to enumerate APIs — it's to help you **pick the right tool for the goal at hand**. ## How the toolset is organized Every workflow reduces to: **find the right process(es) → fetch detail → gather evidence → traverse relationships → synthesize**. | Group | What it covers | When to start here | | ------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------ | | [Standard entry points](/tools/entry-points) | `search`, `fetch` | The default starting path for any process question | | [Process Index](/tools/process-index) | Hierarchy navigation, process details, ranked search | `search` results feel sparse, or you need richer metadata than `fetch` returns | | [Process observations](/tools/observations-and-changes) | Recent changes, observations, activity timelines, sessions | "What changed?", "what happened?", "why does this run this way?" | | [Artifacts](/tools/artifacts) | Document search, content retrieval, in-document text search | The user names a document or recording | | [Workspace](/tools/workspace) | List accessible workspaces | Orienting before drilling in | | [Agent Builder](/tools/agent-builder) | Agent builder instructions and build resources | Building a skill, agent, or automation from your processes | ## Before you call Read [Operating principles](/tools/operating-principles) — the conventions for staying grounded, iterating on search, separating observed from inferred, and avoiding common mis-uses (treating `search_*` snippets as final answers, exposing internal IDs in user-facing prose). ## What the assistant should do with results A human using the Advisor might use two or three tools per question. An assistant in an agentic loop can chain ten or more — searching, drilling in, cross-referencing, synthesizing. The whole point of the MCP is that composition is the value. See [How-to guides](/guides/process-performer) for end-to-end recipes. # Process Index Source: https://developers.within.ai/tools/process-index Discover and navigate the hierarchy of processes the organization runs. Use these tools when [`search`](/tools/entry-points) results feel sparse, or when you need richer process metadata than [`fetch`](/tools/entry-points) returns. | Tool | When to use | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search_processes` | Ranked process search combining keyword matches (name, objective, team, value stream) with semantic similarity. Returns mixed hierarchy-node + process results — use when a top-level value stream or department might be a better starting point than a leaf process. | | `get_process_hierarchy` | Browse the whole index structure. Use when `search` misses, or to orient before drilling in. Cap depth with `max_depth`; the response flags truncated branches and points you at the next call. | | `get_hierarchy_node_details` | Inspect a single hierarchy node — parent, children, linked process, attributes. The right call for a folder / group / value stream key. | | `get_process_details` | The rich nested payload for a process: `current_version`, `dependencies`, `hierarchy_node`, `attributes`, optional version history. Default returns a summary with operational attributes; pass `scope` to include `tasks`, `observations`, `dependencies`, `linked_artifacts`, `policies`, or `history`. This is what [`fetch`](/tools/entry-points) reshapes — use directly when you need the structured shape. | ## Choosing among the lookup tools * **Semantic + keyword, broad** → `search` (entry point) or `search_processes` (richer, mixed results) * **You have a resource key** → `get_process_details` (for processes) or `get_hierarchy_node_details` (for folders / groups / value streams) * **Browse / orient** → `get_process_hierarchy`, then drill in with `get_hierarchy_node_details` or `get_process_details` * **Drill further** (what actually happened on a specific process) → [`get_process_observations`](/tools/observations-and-changes) → [`get_observation_citation`](/tools/observations-and-changes). See [Process observations](/tools/observations-and-changes) for the full toolset. ## Common chains * "What's in this value stream?" → `get_process_hierarchy` (broad) → `get_hierarchy_node_details` on the relevant node → `get_process_details` on each leaf * "Pull every dependency of process X" → `get_process_details` with `scope=["dependencies"]` → walk the `dependencies` list with further `get_process_details` calls * "I have a resource key, give me everything" → `get_process_details` with the scopes you care about (`tasks`, `linked_artifacts`, `history`) * "What actually happens when this process runs?" → `get_process_details` → [`get_process_observations`](/tools/observations-and-changes) → [`get_observation_citation`](/tools/observations-and-changes) on a representative deviation # Workspace Source: https://developers.within.ai/tools/workspace List the workspaces you can access and see which one is active. | Tool | When to use | | ---------------------------- | ----------------------------------------------------------------- | | `list_accessible_workspaces` | List the customer's workspaces and which one is currently active. | All tools in production are read-only. Use `list_accessible_workspaces` to orient at the start of a session or to confirm which workspace the assistant is reading from before drilling in. ## Switching workspaces Each session is scoped to a single workspace. To switch, how you do it depends on how you authenticated: * **OAuth** — disconnect the Within connection in your client and reconnect. The reconnect flow shows a workspace picker. * **API key** — keys are bound to the workspace they were generated in. Generate a new key in the other workspace and swap the Bearer token in your client. See [Authentication → Switching workspaces](/authentication#switching-workspaces) for the full walkthrough. ## Common chains * **Confirm workspace at start**: `list_accessible_workspaces` to see which workspace is active before drilling in