An MCP connector doesn’t cover the whole service – it covers a selection of its API calls, the ones its creators designed it for. With Gmail you see that quickly: MCP will read a message and put a label on it, but it won’t show you what is inside an attachment, and it won’t set up a filter. The rest of the operations sit in the Gmail API itself, waiting for somebody to reach for them directly.

We wrote about this more broadly in the tip on what to do when Claude says there’s no tool for that – that one describes all the routes into a service and the prompt that opens each of them. Today we put that theory to work.

API stands for application programming interface. It is the same service you use through a website and its buttons, exposed to programs as a list of operations they can ask for from the outside. An MCP connector reaches for the API and hands the AI agent a slice of it; your own integration reaches for it with nobody in between.

For an AI agent to talk to the Gmail API, you need three things: a project in Google Cloud Console, the Gmail API switched on inside it, and your own OAuth credentials – a client ID and a client secret that identify your integration to Google. You set all three up in the browser, and you hand the authorisation and the first test to Claude Code.

If all you need is reading and sending mail, stay with the ready-made connector – we show it in the lesson on the Google connectors, where everything goes together in a few clicks.

The Google console is localised into some languages and not others, and the names of translated items can change from month to month. That is why we name every element of the screen in English here – the console was built in English, and that English name is the one to search for when your own screen says something else.

At every screen we also give you a link straight to it, labelled with the word link – you click and you are there, with no menu to hunt through. Google moves the addresses inside the console around, so we make no promise that all of them still work a month from now. When one fails, the name of the page is still right next to it.

The easiest way through this lesson is with Claude Code alongside you: tell it you want to build your own integration with Google Cloud Console, give it the link to this post and set one important condition:

I want to connect my own Gmail integration using Google Cloud Console. Read https://howstart.cc/lessons/build-your-own-google-integration/ and walk me through it step by step. Important: describe one step to me and then wait until I confirm I have it done. Only then move on to the next step.

When you get stuck somewhere – and on a first attempt that is normal – all you have to write is “I can’t see that button” or “I’m getting an error about access being blocked”. You don’t have to find the right spot in the middle of a long set of instructions.

Create a project in Google Cloud Console

Google Cloud Console changes the layout of its screens and their names – the whole authorisation area is called Google Auth Platform today and is split across several separate pages. We take the names of the elements from Google’s documentation; treat the menu layout as a direction, not a map down to the pixel.

A project is the container for everything you do next: the APIs you switch on, the consent screen, the credentials and the quotas. Create it with the Create project button on the Manage resources page – link. In the dialog, give the project a name and choose a Parent resource, meaning an organisation or a folder. An ordinary Google account has neither, so leave that field alone. Google generates the project ID from the name automatically; you can still edit it at this point, but once the project exists, that ID stays with it forever.

Give the project a general name. “Gmail connection” looks sensible for about a week, and stops making sense on the day you switch on the Google Drive API – or any other service – inside the same project, leaving you with a name that lies about its own contents. A name that describes what the integration is for, something like “Office integrations” or “Company automations”, will still be accurate after every further Google service you add.

Projects in Google Cloud

Switch on the API for the service you’re integrating with

A fresh project can’t do anything yet. Access to each Google service is switched on separately, in the API Library: in the menu pick APIs & Services, then Library, and in it the Google Workspace section – link. Click the API you need – for email that is the Gmail API – and switch it on with the Enable button – link.

You aren’t choosing your APIs once and for all – you can switch further services on later, and switch off ones already running if you decide you no longer need them. All of it inside a single integration, with no second project in Google Cloud Console. From here on we work through the example of Gmail; for any other Google service it looks the same, only with a different API and a different scope.

Enabling Google Workspace APIs

The consent screen is the window Google shows you when you log in: the name of the application and the list of permissions it is asking for. In your case there is only one person on the other side of that window – you – but the procedure looks the same as for an application serving a thousand people. In the console these settings sit in the Google Auth Platform area, split across several pages: Branding, Audience, Clients and Data Access.

On the Audience page – link – choose the External user type; that one covers every ordinary Google account, yours included. Below it sits the publishing status, and this is where you click Publish app straight away. A new project starts in Testing status, and that one costs you a fresh login every seven days – that is how long consent lives there, together with the refresh token.

Once the status is In production, no list of accounts narrows down who gets in: formally, anybody with a Google account can log in to your integration. In practice nobody but you will, because to see that window at all you need your client ID and client secret – and those will be sitting in a file on your disk. Google has not verified this application, so at login you’ll see a warning saying it hasn’t been checked; you get past it with the Advanced button. Verification removes that warning and the cap of a hundred new users, and for an integration serving one person you need neither.

Add the scopes on the Data Access page – link. You don’t type them in by hand: a list opens with a search box, you look the scope up by name and click the one you want. A scope governs two things at once: what Google asks you to approve in the consent window, and what the token can do afterwards – and a token can do exactly as much as you grant it during authorisation. There’s an easy reflex here that ruins the whole job: a read-only scope looks careful, and it leaves your integration weaker than the connector you are walking away from. Pick the scopes so that they cover everything the connector could do, and add what it couldn’t. For Gmail, that’s two of them:

  • https://www.googleapis.com/auth/gmail.modify – reading, creating and sending messages, without permanent deletion that skips the bin. It does everything the connector did, and on top of that it gives you the contents of attachments and lets you send HTML-formatted messages, so with bold text, lists and links inside them.
  • https://www.googleapis.com/auth/gmail.settings.basic – Gmail settings and filters, which is what the connector doesn’t touch at all.

Don’t add the https://mail.google.com/ scope. It gives you the same plus permanent deletion outside the bin, and a mistake in a script then removes messages without a trace.

Audience and test users Google OAuth scopes

Generate the OAuth credentials for the application

Credentials are a pair: a client ID and a client secret. Those two are what your integration introduces itself with when it knocks on Google’s door. Create the pair on the Clients page – link – with the Create client button. For the application type, pick Desktop app – that is the one that fits an integration running on your own computer. Leave the rest of the settings alone.

Right after the client is created, download the JSON file with the credentials – in Google’s documentation it goes by client_secret.json. The client secret is visible in that one moment only; afterwards there is no way to look at it or download it again. If you lose it, you have to generate a new secret and swap the file.

We suggest creating a dedicated directory used for nothing but storing access keys, say access-keys.

Apps installed on a computer

Run the first authorisation and collect the token

The clicking in Google Cloud Console ends here. Now you have to turn the file with the client credentials into a token the integration will use day to day – and that is already a job for Claude Code: it writes a short script, runs it on your machine, and reads the error when something doesn’t line up.

In the access-keys directory there is a file client_secret.json with OAuth credentials of the Desktop app type for a project in Google Cloud. Write and run a script that performs a one-off authorisation with the gmail.modify and gmail.settings.basic scopes and saves the refresh token to a file next to it. Show me the login link and wait until I confirm.

What you see then is what anyone signing in to an application with Google sees: a login window and the list of permissions from your consent screen. Once you agree, Google sends a code back to a local address. The script exchanges it for an access token and a refresh token. From that moment on, the integration logs in without you.

After you click through the consent, the browser often lands on a page that looks empty – a white screen and no message at all. That is how it should be: the script has already received the answer, and the page itself has nothing to show you. Tell Claude Code that you have logged in and ask it to finish. If it turns out the script got nothing, copy the address of that empty page out of the browser bar and paste it into the conversation – the code is in that address, and Claude Code will finish the authorisation with it.

If instead of the consent window you get a message about access being blocked, go back to the Audience page – link – and check the publishing status. In Testing, the only account that can log in is one on the list of test users, so click Publish app. With the status In production, no list of accounts limits who logs in, so the cause is somewhere else – most often a scope missing on the Data Access page – link.

How OAuth tokens expire

Plug the credentials into your integration and test it

Before you call the matter closed, check the whole chain: the project, the API switched on, the consent, the token. The simplest way is one real request.

Using the saved token, list the subjects of the three most recent messages in my inbox. Don't change anything in the mailbox or in the key files – this is meant to be read-only.

An error at this stage is useful, because each one points at a different place. A refusal saying the API is not enabled sends you back to the API Library – link. Most often it turns out to be enabled, only in a different project than the one the credentials came from. A refusal over an insufficient scope means the token carries the old set of permissions: adding a scope on the Data Access page – link – changes nothing until you repeat the authorisation and collect a new token.

Add more Google services to the same project

The same project and the same credentials will serve every further Google service. You go back to the API Library – link – switch the next one on and add its scope on the Data Access page – link. You repeat the authorisation, because the old token carries the old set of permissions. You don’t create a second project.

The most useful ones here are the Google Sheets API and the Google Docs API. The ready-made Google Drive connector reads files, renames them and moves them between folders, but it won’t touch the contents of an existing spreadsheet or document. Editing inside a file starts exactly where the connector stops.

Beyond that there is the whole rest of Google, which has no connector at all – claude.ai currently offers three official Google connections: Gmail, Google Calendar and Google Drive. The Google Tasks API lets AI create and tick off items on your task lists. The Google Chat API lets it read and write messages in your company chat. Both services come into your project the same way Gmail did – one click in the API Library, one scope, one authorisation.

Connecting your mail only gives the AI agent access to the tool. To teach Claude Code your way of writing, so that replies to mail sound like yours, read the lesson on the ghostwriter.

Google Workspace connectors Google Tasks API Google Chat API

Keep your access keys safe

There are two files in the access-keys directory now, and the two do different jobs: client_secret.json tells Google which application is asking for access, and the token file holds your consent – that is the one that opens the mailbox. Google’s documentation is brief about both: they belong somewhere only your integration reaches.

So keep that directory outside the project folder you work in with Claude Code, and don’t put it anywhere somebody else will see it – on a shared drive, in an email attachment or in a public code repository.

Don’t paste the contents of those files into a chat either, so that “the AI can check whether everything is right”. A secret inside a conversation stops being a secret, and to check the file Claude Code needs nothing but the path to it.

Storing tokens in a desktop app

What to take away from this lesson

A project in Google Cloud Console is a container, not a connection to one service. Name it generally and add further APIs to it when you need them.

An enabled API and a scope are two different permissions. The first says which service the project reaches at all, the second what a particular token is allowed to do.

A token carries the scopes it was born with. Changing the scopes in the console takes effect only after you repeat the authorisation.

The publishing status decides how long a token lives. In Testing, consent and the refresh token expire after seven days; in production they don’t – which is why an integration meant to work permanently starts with a click on Publish app.

You see the client secret once. You download it while creating the client, keep it in a directory for access keys and show it to nobody – not even the AI, which gets the path to the file and nothing more.

Tasks

Tick them off as you go. The state is kept in your browser, so you can come back to this list tomorrow.

  • Project in Google Cloud Console created and given a general name, not one taken from a single service
  • API of the service you’re integrating with switched on in the API Library – link
  • Application published – In production status on the Audience page – link
  • Scopes gmail.modify and gmail.settings.basic added on the Data Access page – link
  • File with the client credentials downloaded and saved in the directory for access keys
  • First authorisation done, token saved on disk
  • One real request made using the token, with the result confirming the integration works