> 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

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. Open the MCP Servers modal and move to the MCP External tab.

  2. Click Connect to Notion.

  3. 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.

Use Port's remote MCP server for new connections. The Docker image and uvx mcp-server-port package from the deprecated local MCP server repository are no longer maintained. If you used that server, remove its entry from your client's MCP configuration and follow the setup below.

Select your client and Port region, then follow one setup path. Use the EU endpoint (https://mcp.port.io/v1) for app.port.io, or the US endpoint (https://mcp.us.port.io/v1) for app.us.port.io.

Cursor, VS Code, GitHub Copilot CLI, and Claude Code can connect directly over HTTP. The mcp-remote package is a local compatibility proxy for clients that need it; it connects to the same remote Port server and is separate from the deprecated Docker/uvx server.

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

For the EU region, you can use the Cursor install link and continue with authentication in step 3. For the US region, or to configure the connection manually, follow all steps below.

  1. Open Cursor settings

    In the settings, click Customize, select MCPs, and then click New MCP Server.

    Cursor Customize settings with MCPs selected and New MCP Server highlighted

  2. Configure the MCP server

    Add the following configuration:

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

    If your Port organization is in the US region, replace https://mcp.port.io/v1 with https://mcp.us.port.io/v1.

    Cursor mcp.json defining a port-remote server with the Port US MCP URL
    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.

  3. Authenticate with Port

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

    Cursor MCP Tools settings showing port-remote enabled 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.

    Connected port-remote server in Cursor listing available blueprint, entity, scorecard, and action 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.