Service Account Integration

A service account is a non-human MarcoPolo identity with its own workspace. Your application holds its API token on the server and makes calls as that identity. This is the simplest application integration when every caller may use the same set of granted connections.

Service accounts require the service account feature for your organization. The person setting one up needs access to Developer Tools and permission to manage the connections they grant.

Set up the service account

1. Sign in to the MarcoPolo web app. In Developer Tools, create a service account and give it a name tied to the application or agent that will use it.
2. Add the data connections in Connections using appropriately scoped provider credentials. You create and manage these as an authorized person; the service account receives access through grants.
3. Open the service account in Developer Tools and use its Explicit connection grants section to select the connections it may use. Granting a connection makes it available in the service account's workspace.
4. Create a token for the service account. Copy it when shown, store it in your application's server-side secret store, and record when it expires. The token is shown only once.
5. Start the application with that token and verify the service account can see the intended connections.

Use MCP from an agent framework

Configure your framework's Streamable HTTP MCP client with the MarcoPolo server URL and the service account token. The hosted URL is https://mcp.marcopolo.dev; use your deployment's URL for BYOC. Load the token from your server-side secret store. Once connected, the agent can use MarcoPolo's MCP tools against the service account's granted connections and workspace.

The short examples below assume these server-side values:

import os

MCP_URL = os.getenv("MARCOPOLO_MCP_URL", "https://mcp.marcopolo.dev")
access_token = os.environ["MARCOPOLO_SERVICE_ACCOUNT_TOKEN"]

LangChain and LangGraph

With langchain[mcp], the LangChain MCP adapter can expose MarcoPolo tools to a LangChain agent or LangGraph workflow. FastMCP bearer authentication adds the Bearer prefix for the token.

from fastmcp import Client
from langchain.mcp import MCPAdapter


async def load_marcopolo_tools():
    async with MCPAdapter(Client(MCP_URL, auth=access_token)) as adapter:
        return await adapter.list_tools()

Pass the returned tools to your agent or graph. Do not include Bearer in access_token when using FastMCP's auth parameter.

Google ADK

Add this MCP toolset to your ADK agent's tools list:

from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

marcopolo_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url=MCP_URL,
        headers={"Authorization": f"Bearer {access_token}"},
    )
)

Microsoft Agent Framework

Pass this Streamable HTTP MCP tool to your Agent Framework agent. The header provider supplies the credential when the framework connects and calls tools.

from agent_framework import MCPStreamableHTTPTool

marcopolo_tools = MCPStreamableHTTPTool(
    name="marcopolo",
    url=MCP_URL,
    header_provider=lambda _: {"Authorization": f"Bearer {access_token}"},
)

Use SDK APIs from an enterprise application

The service account is also an identity for traditional, non-AI applications. Your application backend can pass its token to the MarcoPolo Python SDK and call the Data Gateway directly. It does not need an agent framework or MCP client. The same approach works when an AI application needs a deterministic API call instead of asking an agent to choose an MCP tool.

For example, query a connection granted to the service account and return a small result to your application:

import os
from marcopolo import Marcopolo


async def query_app_data(connection_name: str, query_text: str):
    async with Marcopolo(
        access_token=os.environ["MARCOPOLO_SERVICE_ACCOUNT_TOKEN"]
    ) as client:
        operation = await client.operations.query(
            connection_name,
            source={"kind": "query_text", "text": query_text},
            inline=True,
            inline_limit=100,
        )
        if operation.status != "succeeded":
            raise RuntimeError(operation.failure)
        return operation.result.records.rows

Use query_text for connections that support SQL-like queries. For other sources, the SDK also supports provider operations and saved queries. Your backend can inspect granted connections with client.workspace.connections(), explore schemas with client.catalog, and manage supported connections with client.connections. See the Python SDK guide for those workflows. All calls run in the service account's workspace and are limited to its granted connections; the token does not grant access to other tenant connections automatically. For BYOC, pass your deployment's URL as base_url when creating Marcopolo.

Do not put the service account token in browser code, a mobile app, a prompt, or a repository. Your application authenticates its own users and decides which requests may use this shared MarcoPolo identity.

Grow beyond one shared identity

If application roles need distinct sets of shared connections, create a service account for each role and route requests to the appropriate token. If each person's connections, workspace, permissions, or audit identity must remain separate, use a dedicated MarcoPolo namespace.

You can revoke a service account token in Developer Tools. Disabling the service account revokes its active credentials. Review connection grants and rotate tokens as part of your application's normal credential management.