Skip to main content

FastMCP quickstart

AvailableFreeAvailableIndividualAvailableTeamAvailableCustom Compare plans

In this tutorial, you'll create a new Python project with uv, build a FastMCP server that exposes one of Airbyte's agent connectors as an MCP tool, and use it to query GitHub data from any MCP-compatible agent. This tutorial uses GitHub, but if you don't have a GitHub account you can swap in any other agent connector and perform different operations.

Your MCP server executes through Airbyte. Airbyte Agents owns the OAuth apps, stores your third-party tokens, and refreshes them for you. Your Python code only ever sees your Airbyte client ID and client secret.

Overview​

This tutorial is for AI engineers and other technical users who work with data and AI tools. You can complete it in about 15 minutes.

The tutorial assumes you have basic knowledge of the following tools, but most software engineers shouldn't struggle with anything that follows.

  • Python and package management with uv
  • MCP (Model Context Protocol) and MCP servers
  • GitHub, or a different third-party service you want to connect to

Before you start​

Before you begin this tutorial, ensure you have the following.

Part 1: Create a new Python project​

Create a new project using uv:

uv init my-mcp-agent --app
cd my-mcp-agent

This creates a project with the following structure:

my-mcp-agent/
├── .gitignore
├── .python-version
├── main.py
├── pyproject.toml
└── README.md

Part 2: Install dependencies and create your server file​

  1. Install the Agent SDK and FastMCP:

    uv add airbyte-agent-sdk fastmcp python-dotenv

    This command installs:

    • airbyte-agent-sdk: The Agent SDK, which ships every connector as a typed submodule.
    • fastmcp: A Python framework for building MCP servers with minimal boilerplate.
    • python-dotenv: A library you can use to load environment variables from a .env file.

  2. Create a server.py file with the following imports:

    server.py
    import json

    from dotenv import load_dotenv
    from fastmcp import FastMCP
    from airbyte_agent_sdk import connect
    from airbyte_agent_sdk.connectors.github import GithubConnector

    These imports provide:

    • json: Serialize connector results for the MCP tool return value.
    • load_dotenv: Load environment variables from your .env file.
    • FastMCP: The FastMCP server class that handles MCP protocol communication.
    • connect: The Agent SDK entry point. One call returns a typed connector bound to your workspace.
    • GithubConnector: The connector class. You reference it when decorating the tool so the SDK can describe the connector's entities and actions to the agent.

Part 3: Add a .env file with your secrets​

  1. Create a .env file in your project root and add your Airbyte API credentials to it. Replace the placeholder values with your actual credentials.

    .env
    AIRBYTE_CLIENT_ID=your-airbyte-client-id
    AIRBYTE_CLIENT_SECRET=your-airbyte-client-secret

    Copy AIRBYTE_CLIENT_ID and AIRBYTE_CLIENT_SECRET from the Profile page on app.airbyte.ai.

    warning

    Never commit your .env file to version control. If you do this by mistake, rotate your secrets immediately.

  2. Add the following line to server.py after your imports to load the environment variables:

    server.py
    load_dotenv()

Part 4: Add the GitHub connector​

Before you can query GitHub data, add a GitHub connector to your Airbyte Agents workspace. You can do this through either the web app, MCP, or API.

  • Web app: Open app.airbyte.ai, click Connectors, click Add Connector, search for GitHub, and complete the authentication flow with your GitHub personal access token. See Add a connector (UI) for a full walkthrough.

  • API: Send a POST request to create the connector programmatically. See Add a connector (API) for request examples.

  • MCP: If you run the Agent MCP, you can add a new connector from your existing agent. See Agent MCP to learn how to use the MCP server.

You only need to add the connector once. After it exists in your workspace, you can skip this step when setting up new agents.

Part 5: Configure your MCP server​

Now add the following code to server.py to connect to the GitHub connector and create the FastMCP server.

Create the server and connector​

server.py
mcp = FastMCP("GitHub Agent")

github = connect("github")

FastMCP("GitHub Agent") creates a new MCP server named "GitHub Agent".

connect("github") does four things for you:

  • Reads AIRBYTE_CLIENT_ID and AIRBYTE_CLIENT_SECRET from the environment.
  • Defaults to the "default" workspace, which is where the web app stores credentials unless you change it.
  • Returns a typed GithubConnector bound to the GitHub connector in your workspace.
  • Routes every github.execute(...) call through Airbyte's hosted API, which holds the GitHub tokens and refreshes them for you.

If you want to connect to a different workspace or pass credentials explicitly, use connect("github", workspace_name="my-workspace", client_id=..., client_secret=...) or pass an AirbyteAuthConfig. See the SDK reference for details.

Register the tool​

Rather than one tool per GitHub endpoint, the Agent SDK exposes the entire GitHub API through a single execute(entity, action, params) entry point. This one-tool-per-connector model is context-efficient: instead of registering dozens of tools that consume the agent's context window, a single tool with a compact entity/action catalog gives the agent full connector coverage with minimal overhead.

The @GithubConnector.tool_utils decorator fills in the entity and action catalog as part of the tool description, so the agent knows what's available without you writing a schema. It also enables automatic fallback to the list action when the Context Store is not yet ready, so your tool works immediately even before the first replication completes.

server.py
@mcp.tool()
@GithubConnector.tool_utils
async def github_execute(entity: str, action: str, params: dict | None = None) -> str:
    """Execute GitHub connector operations."""
    result = await github.execute(entity, action, params or {})
    return json.dumps(result, default=str)

The decorator stack is the whole tool definition. No per-action docstring, no GITHUB_LIST_COMMITS or GITHUB_GET_PR sprawl, one entry point that covers the full connector. @GithubConnector.tool_utils appends the full entity and action catalog to the tool description so the MCP client sees every entity, action, and enum value the connector supports. As the connector grows, the tool signature stays the same.

Each execute call returns a structured result with data (the records) and meta (pagination cursors). MCP tools return strings, so this tutorial serializes the whole result with json.dumps so the MCP client can reason about both the records and the pagination state.

Add the server entry point​

Add the following at the bottom of server.py to start the server when run directly:

server.py
if __name__ == "__main__":
    mcp.run()

Part 6: Register with your agent​

Register the MCP server with your preferred agent. Provide the full path to your project's server.py file. Replace /path/to/my-mcp-agent with the actual path to your project directory.

claude mcp add github-agent -- uv run --directory /path/to/my-mcp-agent server.py

Part 7: Use the MCP server​

  1. Restart your agent so it picks up the new MCP server registration.

  2. Once restarted, prompt your agent with natural language questions about your GitHub data. Try prompts like:

    • "List the 10 most recent open issues in airbytehq/airbyte"
    • "What are the 10 most recent pull requests that are still open in airbytehq/airbyte?"
    • "Are there any open issues that might be fixed by a pending PR?"

Your agent discovers the MCP server's tools automatically and calls them based on your prompts. The MCP server hands each tool call off to Airbyte, which executes the operation against GitHub and returns the result.

Troubleshooting​

If your agent fails to retrieve GitHub data, check the following:

  • Server not found: Ensure the path in your MCP configuration points to the correct server.py file and that uv is available on your system PATH.

  • HTTP 401/403 errors from Airbyte: Verify that AIRBYTE_CLIENT_ID and AIRBYTE_CLIENT_SECRET are copied correctly from your Profile page on app.airbyte.ai.

  • "No connector found" or "connector not configured": Make sure you added the GitHub connector to your workspace before starting the MCP server. connect("github") defaults to the "default" workspace; if you created the connector in a different workspace, pass workspace_name="your-workspace-name" to connect().

  • HTTP 401/403 errors from GitHub: The GitHub token stored in your connector is invalid or missing required scopes. Verify that the token you provided when adding the connector has repo scope.

  • Empty data=[] responses from filtered queries: Most GitHub filters use case-sensitive values. Confirm the agent is sending uppercase values (for example, states=["OPEN"] rather than states=["open"]). The tool description's rules nudge the model to do that by default; you can also reinforce the rules in your client's system prompt.

See the Github agent connector page for more details.

Summary​

In this tutorial, you learned how to:

  • Set up a new Python project with uv
  • Add FastMCP and Airbyte's GitHub agent connector to your project
  • Configure environment variables for your Airbyte Agents credentials
  • Register a single MCP tool that covers the entire GitHub API
  • Register your MCP server with an agent and use natural language to interact with GitHub data through Airbyte

Next steps​

  • Learn more about the SDK: See the full SDK interface tutorial and reference documentation.

  • Let your AI assistant scaffold the next agent. The Agent SDK ships skills for Claude Code and Codex that carry the patterns above, so you can ask your assistant to build a new agent quickly. See the airbyte-agent-sdk repository for installation instructions.

  • Reach the same connectors from any other interface. Airbyte Agents exposes the same connectors through all of its interfaces. Since you already added a connector, you can use that connector anywhere you use Airbyte Agents.

Was this page helpful?