Choose an Integration
Choose whose identity MarcoPolo uses and whether your application connects through MCP, the Python SDK, or REST.
MarcoPolo gives each identity a workspace and governs which connections it can use. First choose a deployment, then decide whose identity should run the work and how your application will call MarcoPolo.
The three integration paths
AI assistant with your own identity
Connect Claude, ChatGPT, Cursor, or another assistant to the MarcoPolo MCP server and authorize it as yourself. The assistant's requests use your workspace and the connections you can access. Connect an AI assistant.
Enterprise application with a service account
A developer manages connections and grants them to the service account in the web app, then stores its token on the application backend. Every request using that token runs as the service account. Set up a service account.
MarcoPolo namespace with per-user workspaces
The MarcoPolo team provisions a dedicated MarcoPolo namespace and its key for your application. For each authenticated user, the backend requests a short-lived user token. MarcoPolo selects or provisions that user's workspace. Your application can use the SDK to create field-based connections, start hosted OAuth setup for users, and run queries as that user. Use a MarcoPolo namespace.
Choose an identity
| Your situation | Identity and credential | What users share | Start here |
|---|---|---|---|
| You use Claude, Codex, or another AI assistant yourself | Your user identity, established when you connect the assistant through MCP | Your workspace is yours; connection sharing follows MarcoPolo permissions | Connect an AI assistant |
| You are testing application code against your own data | Your personal API token from Developer Tools | Calls use your workspace, permissions, and audit identity | Python SDK quick start |
| Your application serves users who may use the same set of data connections | A service account API token, held by your application server | All callers use that service account's workspace and explicitly granted connections | Service account integration |
| Your application needs separate connections, workspaces, permissions, or audit identity for each user | A MarcoPolo namespace key that your backend exchanges for short-lived user tokens | Each authenticated user gets their own workspace within the namespace | MarcoPolo namespace with per-user workspaces |
Use a service account only when its connection grants are appropriate for every application user who can trigger calls with that account. Separate service accounts can serve distinct application roles; use per-user tokens when access or audit needs to follow each individual.
Choose an interface
| Interface | Use it when | Connection management |
|---|---|---|
| MCP | An AI assistant or agent framework should discover and call MarcoPolo tools | Configure and grant connections in the web app. The documented MCP workflow uses existing connections. |
| Python SDK | Python application code needs typed connection, query, catalog, or workspace operations, or you want the SDK's agent toolkit | Create field-based connections directly or start a hosted OAuth setup session and send the user to the provider. The web app also supports provider authorization. See the SDK guide. |
| REST API | Your application is not written in Python or needs direct HTTP integration | Use the same governed API behavior as the SDK. Keep bearer credentials on your backend. |
MCP and the SDK can use the same personal, service account, or namespace-issued identity. Your choice of interface does not change whose connections and workspace the call can access.
Understand the boundaries
A deployment hosts one or more logical namespaces. A namespace contains tenants, identified by work email domain. A tenant contains people and, where available, service accounts. Each identity has its own persistent workspace; access to a connection is granted separately. See Identity and workspaces for the terms and an example.
The hosted service and available BYOC environments are covered in Choose a Deployment. Deployment location does not by itself decide whether your application should use a personal token, service account, or a user token from a dedicated MarcoPolo namespace.