> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Onboard developers using internal docs and Port MCP

Implement with AI

Send this guide to your coding agent.

Prerequisite: Install Port MCP

Open in ClaudeOpen in CodexOpen in Cursor
Open plan mode. Implement this Port guide in my org via MCP:

https://docs.port.io/guides/all/onboard-developers-from-internal-docs-using-port-mcp

Goal: get the guide's core flow working end-to-end in my org; adapting it to fit my existing setup takes priority over matching the guide 1:1.

Plan:
1. Confirm MCP is connected, in the right org, with sufficient permissions.
2. Diff the guide's data model (blueprints, properties, relations, actions, agents, automations, integrations, secrets) against mine.
3. Propose adaptations for gaps, reusing existing blueprints/relations over guide-named duplicates.
4. Flag what needs a UI click, credential, or secret from me, testing MCP capability empirically before ruling anything out.
5. Stop on any blocker and give me options. Approving this plan authorizes the writes it lists; pause only for writes beyond what's listed.

Build:
- Extend blueprint schema additively when upserting; don't remove or overwrite existing properties, and treat type conflicts as a blocker, not an auto-fix.
- List any mock data in the plan, minimal and labeled mock; once approved, seed it without re-asking, and tell me what you seeded.
- For anything the guide writes downstream (e.g. a webhook target), use a real entity, not a mock.
- For pages/widgets, use the real page identifier from the app URL, not a guessed slug.
- When you hit a UI step confirmed (not assumed) unsupported via MCP, pause, give exact clicks, then resume via MCP.
- Validate and give links after each meaningful step (only a tool-returned URL, no guessed paths); don't proceed if the last run wasn't a success.

Done:
- Confirm the guide's expected output exists and runs in Port.
- Summarize adaptations, seeded data, what was mocked or skipped, remaining UI steps, and how to verify.

This guide shows how to onboard a new platform engineer using Cursor and Port MCP. You will connect Notion through Port MCP connectors, register a custom onboarding skill in Port, connect Cursor to Port MCP, and test onboarding questions grounded in your internal documentation.

Common use cases​

  • Reduced onboarding overhead: Reduce the time engineering teams spend answering repetitive onboarding questions from new hires.
  • Standards enforcement: Surface approved scaffolding patterns and deployment processes so engineers follow org standards from day one.
  • Architecture discovery: Help engineers understand existing decisions and system designs by querying connected Notion and Port content.

Prerequisites​

This guide assumes you have:

  • A Port account with the skills blueprint configured.
  • Cursor IDE installed (you can also use VSCode, Claude, or other MCP-compatible tools).
  • Relevant onboarding content in your knowledge sources - Notion pages and Port Context Lake are both supported.
  • A Notion workspace with internal documentation such as an onboarding guide, architecture decision records, and approved tooling pages.

Connect to Notion remote MCP​

Connect to the Notion MCP server using Port MCP connector capabilities. You can learn more in MCP connectors.

  1. Go to your platform in Port.

  2. Click your avatar in the top-right corner.

  3. Open MCP Servers.

  4. Move to the MCP External tab.

  5. Click Connect to Notion.

  6. Complete the authentication flow for your account.

    Notion MCP connector connection in Port

Create the onboarding skill​

Create the skill that will be invoked whenever a developer asks an onboarding question. Ensure you have created the skills blueprint in Port before proceeding.

  1. Go to the Skill catalog page in Port.

  2. Click the + Skill button.

  3. Toggle JSON Mode.

  4. Copy and paste this JSON configuration:

    Onboarding skill entity (click to expand)
    {
      "identifier": "developer_onboarding_assistant",
      "title": "developer-onboarding-assistant",
      "icon": "Learn",
      "team": [],
      "properties": {
        "description": "Answer developer onboarding and internal engineering questions using Notion, Port Context Lake, and connected MCP tools. Use when a developer asks about onboarding, how to do something internally, where to find docs, or what the approved devops patterns are.",
        "instructions": "---\nname: developer-onboarding-assistant\ndescription: Answer developer onboarding and internal engineering questions using Notion, Port Context Lake, and connected MCP tools. Use when a developer asks about onboarding, how to do something internally, where to find docs, or what the approved patterns are.\n---\n\n# Developer onboarding assistant\n\nUse this skill to answer developer questions about internal systems, standards, and workflows.\nAlways ground answers in connected documentation sources (Notion, Port, Context Lake).\nDo not rely on generic knowledge if internal sources are available.\n\n---\n\n## Step 1: Understand the question\n\n1. Parse the user's question and identify:\n\n   * **Intent** - onboarding, how-to, architecture, standards, troubleshooting\n   * **Key entities** - service name, platform (e.g. OAuth), tool (Port, CI/CD, etc.)\n2. Normalize the query into 2-3 search-friendly phrases:\n\n   * e.g.\n\n     * \"onboard service port\"\n     * \"microservice scaffolding standard\"\n     * \"oauth architecture decision record\"\n\n---\n\n## Step 2: Discover available knowledge sources\n\n1. Use `list_entities` on `_mcp_server` where `exposed = true`\n2. Identify available knowledge sources:\n\n   * **Notion** - tools like `notion-search`, `notion-fetch`, etc.\n   * **Port** - `search_port_knowledge_sources`\n   * **Context Lake** - blueprints that may contain internal docs (runbooks, ADRs, guides)\n3. Determine:\n\n   * Is **Notion connected and usable**?\n   * What **fallback sources** are available?\n\n---\n\n## Step 3: Search Notion (primary source)\n\nIf Notion tools are available:\n\n1. Use `notion-search` (or equivalent) with the normalized queries\n\n   * Search across titles + content\n   * Prioritize:\n\n     * onboarding guides\n     * runbooks\n     * ADRs (Architecture Decision Records)\n     * engineering standards\n\n2. Select the most relevant 1-3 documents:\n\n   * Prefer exact matches (service name, platform, workflow)\n   * Then semantic matches (related systems or patterns)\n\n3. Use `notion-fetch` (or equivalent) to retrieve full content\n\n4. Extract:\n\n   * Key steps and instructions\n   * Official patterns or standards\n   * Links to related docs\n   * Any warnings, prerequisites, or constraints\n\n---\n\n## Step 4: Fallback to Port and Context Lake\n\nIf:\n\n* Notion is **not connected**, OR\n* No relevant documents are found\n\nThen:\n\n1. Use `search_port_knowledge_sources` with the same queries\n2. Additionally, query Context Lake:\n\n   * Use `list_entities` on relevant blueprints (e.g. `service`, `runbook`, `adr`, `documentation`)\n   * Look for:\n\n     * embedded documentation fields\n     * related entities (services, systems, components)\n3. Extract any relevant internal guidance\n\n---\n\n## Step 5: Synthesize the answer\n\nProvide a clear, actionable response:\n\n1. **Direct answer first**\n\n   * step-by-step if it is a how-to\n   * concise explanation if conceptual\n\n2. **Ground in sources**\n\n   * Reference the document(s) used (Notion or Port)\n   * Prefer linking to the original doc if available\n\n3. **Structure based on intent**\n\n   * **How-to** -> steps\n   * **Standards** -> rules + rationale\n   * **Architecture** -> summary + decisions\n\n4. If multiple sources:\n\n   * Merge into a single consistent answer\n   * Resolve conflicts (prefer most recent and authoritative)\n\n---\n\n## Step 6: Handle gaps gracefully\n\nIf no strong answer is found:\n\n1. Clearly state:\n\n   * No relevant Notion or Port documentation was found\n2. Provide:\n\n   * The closest related information (if any)\n3. Suggest next steps:\n\n   * Who to ask (team, owner from Context Lake if available)\n   * Where to look next (repo, Slack channel, etc.)\n\n---\n\n## Response guidelines\n\n* Be **concise but practical**\n* Prefer **internal truth over general best practices**\n* Always **prioritize Notion -> then Port -> then Context Lake**\n* Never hallucinate internal processes - if unsure, say so\n* Include **links to source documents** when available\n\n---\n\n## Example queries this skill handles\n\n* How do I onboard a new service into Port?\n* What's the approved way to scaffold a new microservice?\n* Where are the OAuth architecture decision records?\n* How do we handle secrets management in this org?\n* What's the deployment process for backend services?\n"
      },
      "relations": {}
    }

  5. Click Register to add the new skill.

Set up Port MCP server in Cursor​

The Port MCP server enables you to interact with Port data and connected tools using natural language queries directly from your IDE.

Follow the instructions for your preferred tool below:

To connect Cursor to Port's remote MCP, follow these steps:

  1. Open Cursor settings

    Go to Cursor settings, click on Tools & Integrations, and add a new MCP server.

    Cursor Settings Tools and Integrations panel

  2. Configure the MCP server

    Add the appropriate configuration for your Port region:

    {
      "mcpServers": {
        "port-eu": {
          "url": "https://mcp.port.io/v1",
          "headers": {
            "x-read-only-mode": "0"
          }
        }
      }
    }
    Read-only mode

    The x-read-only-mode header defaults to 0, which allows all tools based on your permissions. You can change it to 1 to restrict the MCP server to only expose read-only tools. When set to 1, write tools are completely hidden from the available tools list, ensuring you can only query data without making modifications.

    Cursor mcp.json with Port MCP server URL

  3. Authenticate with Port

    Click on "Needs login" and complete the authentication flow in the window that opens.

    Cursor MCP Tools panel with Needs login status
    Cursor OAuth session persistence

    Port MCP authentication works on the initial connection. If Cursor prompts you to re-authenticate every day or two, this is typically caused by a known Cursor OAuth issue rather than a Port-side session or configuration problem.

    When Cursor refreshes your OAuth session, it may fail to persist or update tokens correctly. This is especially common when you have multiple Cursor windows open. Port's logs may show invalid_grant errors when Cursor attempts to refresh with a stale token.

    For more details and workarounds, see these Cursor community discussions:

    Cursor has reported fixes for some MCP OAuth issues in stable releases after May 12, 2026. If you experience frequent re-authentication, update Cursor to the latest stable version and check whether the issue persists.

  4. Verify connection

    After successful authentication, you'll see the list of available tools from the MCP server.

    Cursor MCP Tools connected with Port tools

Test your setup​

Once Port MCP is configured in Cursor, test the onboarding workflow with the queries below.

Start a new chat session​

  1. Open a new chat session in Cursor (Cmd/Ctrl + L).
  2. Confirm Port tools appear in the tools panel.
  3. Start your conversation with onboarding queries.

Example onboarding queries​

Here are practical queries you can use to validate that the skill is pulling from your connected Notion and Port content.

Ask:

"I'm a new developer — what's the onboarding process and what should I do first?"

Expected result:

  • The response should pull from your Developer onboarding guides in Notion.

    Onboarding process query and response in Cursor

Ask:

"I'm working on the payments service. Who owns it and where can I find their onboarding architectural docs?"

Expected result:

  • The response should include service metadata from Port's context lake. It should also surface your Architecture decision records page in Notion and reference the relevant ADR entries, such as the decision to adopt Port MCP Connectors as the approved AI gateway.

    Architecture decision records query and response in Cursor

What to check​

  • Every answer is grounded in your Notion pages and Port Context Lake - not generic AI responses.
  • The assistant references specific content from your internal docs (ADR numbers, tool names, exact steps).
  • The assistant does not invent internal processes, links, or tooling that is not in your sources.
  • If a topic is not covered in any connected source, the assistant says so and suggests where to look next.